Twitmonger Readme

Version alpha 0.5.

Last Updated: 04/29/12

prerelease software warning.


What is Twitmonger?

Twitmonger is a client for the Twitter microblogging service.

Twitmonger is extremely intuitive to use. After reading through this document, it's likely you'll be using it easily and efficiently in no time. We hope you enjoy the software, and feel free to submit feedback and suggestions to the tracker.

Twitmonger works with most screen readers, including Jaws, Window Eyes, system access, Hal, SuperNova and the freely available NVDA. Note that NVDA support requires NVDA 2010.1 or later.

General Twitmonger concepts

what are buffers?

Buffers are separate areas within Twitmonger that are used to hold different types of information for review. We'll show you how to utilize them throughout this document.

Twitmonger remembers the last buffer you were reading, even when you restart the application. To switch between the various buffers, use ctrl+win+left and right arrows. Twitmonger will announce the buffer you change to, so you'll always know where you are. Once you've picked a buffer you want to read through, use control+win+up and down arrows to browse the items.

To go to the most recent or oldest item in the buffer, use ctrl+win+home or end respectively. To move forward or back through the list by 5%, press control+win+page up or down. To move forward or back by an hour, use control+win+shift+page up or down. You can adjust how much these commands move in the navigation tab of Twitmonger's main configuration dialog, available by pressing control+shift+win+o. You can also use control+win+z to undo the last navigation command you issued.

If you wish to manually update the buffer you're in, rather than waiting for it to update itself at whatever interval you chose during configuration, use ctrl+win+u. If you ever wish to delete the contents of a buffer from your Twitmonger database, you can do so by pressing ctrl+shift+win+delete. When the buffer updates again, the newest items will be back in the buffer, up to the maximum that you configured.

You can also modify the navigation order of the buffers by pressing control+win+alt+left or right arrows to move the current buffer in that direction.

Options when sending messages in Twitmonger

Often when using Twitmonger, you will be entering messages that you wish to send. All of the message composition dialogs in Twitmonger share many common characteristics. This section describes the options that you have in these dialogs.

Delaying a message

You have the option to schedule a message to be sent out at a later time. Anywhere that you would compose something, there is a button which brings up a dialog for you to schedule the message. The first option in this dialog is the scheduling method. If you select the interval method, you can set the number of hours, minutes and seconds that Twitmonger will wait before sending your message. Using the time method, you enter the exact time you wish to send the message. You must enter the time in 24-hour format rather than in am/pm format.

Shortening and unshortening URLs

The idea behind URL shortening is that a long address is replaced by a shorter one. This gives you more characters in situations where you have a limit to work with such as tweets or sms messages . You may select your preferred shortener from the Miscellaneous tab of the global Configuration dialog, available by pressing control+shift+win+o. Within any dialog where you would compose something, you will find buttons to shorten or unshorten any URL in the message.

If your URL starts with "http://" or "www." (no quotes), it will be automatically detected. Pressing alt+s or clicking on the "Shorten URL" button will replace your long URL with a shorter one. If the URL you want to replace isn't automatically detected, you can select it and press alt+s which will use your selection. If more than one URL is detected, you'll be presented with a list allowing you to select the URL you wish to shorten.

Keyboard Help

We Highly recommend that you read all of this document to get a complete understanding of how Twitmonger's various functions work. After you have done that, however, there is a way to quickly remind yourself what a particular keystroke does. The keyboard help mode can be turned on by pressing control+win+shift+k. In this mode, pressing a Twitmonger command will inform you what that keystroke does. Press control+win+shift+k again to exit keyboard help mode.


Twitmonger is actually a very flexible piece of software. Most of this document discusses Twitmonger's default behavior. Pressing control+win+o will bring up a configuration dialog with options for Twitter. Pressing control +shift+win+o will bring up the main configuration dialog with options that apply to all of Twitmonger.


What is Twitter?

Twitter is an insanely popular micro blogging service, that is, a service which allows you to post short little chunks of no more than 140 characters of text to the web at a time and have these updates, or tweets, as they are called in twitter speak, read by your followers, or the people who are following you. If you don't currently have a twitter account, you may create one here

Twitmonger was originally created to make using the Twitter system as easy and efficient as possible. There are many advantages to using a Twitter client, and Twitmonger in particular. Here are just a few:

logging into twitter

The first time you open a twitter account, your web browser will open and load a twitter web page which will askyou to enter your twitter username and password to authorize Twitmonger. After logging in, twitter will provide you with a number. Return to Twitmonger, enter this number and you will be ready to get started. The following sections will tell you everything you need to know about using Twitter.

Note: there have been a few reports of trouble connecting to twitter when certain firewalls are in use. The most common problems are with the Vipre firewall. If you are unable to connect, you may need to add an exception to the firewall. In the case of Vipre, you want to add as a web exception. Generally, you either need to create an exception for or for the Twitmonger application itself.

about API calls

Throughout this chapter, you will see references to API calls. Twitter has a limit on how much data you can get from the site in a given hour. Any time you use Twitmonger or any other twitter client to download tweets, it counts against this limit. Press control+win+a to check how many API calls you have left for the hour and how long until your limit will be reset.

In most cases, one call to twitter's API can get 200 tweets. By default, Twitmonger will only use 1 API call for any operation. You can change this in the default settings tab of the buffer configuration dialog, available with control+win+alt+o. This dialog will be fully discussed in a later section. You need to always keep this fact in mind whenever changing a setting that will use more API calls than the default. We have chosen tdefault settings that will insure that you should not run up against your hourly limit.

Buffers for Twitter

In a Twitter account, there are four default buffers, or collections of posts. They are home, direct messages, sent, and mentions.

The home buffer holds all received tweets, except for direct messages. These are the tweets of the users you have chosen to follow.

The direct messages buffer holds any direct messages you receive. Direct messages are a way of sending a message that only the person that you want to receive the message can see, or vice versa.

The sent buffer, logically, contains all the tweets and direct messages that you've sent.

The mentions buffer contains all of the tweets that contain mentions of your screen name. In twitter, if you make a comment that someone wants to respond to, they can make what is referred to as a mention, or reply. From the website they would have to type an @ followed by your username. However in Twitmonger we take care of that. (see the section on replying.

Twitmonger now utilizes a newer feature of twitter to instantly update your Mentions and Direct Message buffers. Unlike all other buffers in Twitmonger, they are automatically updated instantly as soon as you receive a new message, without waiting the normal length of time for an update.

The buffer configuration dialog

There are a few options that can be set differently for each type of buffer. Control+win+alt+o will bring up the buffer configuration dialog. The default settings tab will set the defaults for any new buffer that you create, such as searches or individual timelines. You can check the apply settings to all buffers checkbox to use these settings for buffers that already exist.

This dialog has a tab with settings for each buffer. When you open the dialog, the tab for the buffer that you are currently working in will be the default. If you change buffers while this dialog is open, the active tab of the dialog will change to match your current position. The settings available in this dialog are described below.

The first option is the update interval. This allows you to choose how often Twitmonger checks for updates in a given buffer. The default is 3 minutes. This is the minimum in the default settings tab. You can set a particular buffer as low as 1 minute, but this is not recommended. If you are not careful about this, you may run out of API calls.

Next we have the max number of tweets to retrieve option. This is basically exactly what it says: how many tweets should Twitmonger download at once? The default is 200, which is the highest allowed by twitter.

If the previous option was set to 200, you have the option of using more than 1 API call if necessary to get caught up on tweets. The next option is the maximum number of API calls to use. Each API call gets up to 200 tweets. Again, this will use more of your hourly API call limit.

The next option controls whether this buffer is muted. If it is checked, you will not be notified by sound or speech when new items arrive in this buffer during an automatic update. If you manually check for updates, you will get spoken feedback without sounds.

The next two options determine how Twitmonger formats information. The spoken template specifies how tweets in this buffer will be spoken, and the clipboard template sets the format used for copying them to the clipboard. First you will find two checkboxes, allowing you to specify that the default templates should be used. If these checkboxes are unchecked, you will be able to set a different template for this buffer. The default templates can be modified in the twitter configuration dialog, available by pressing ctrl+win+o. For more on how to use these options, see the templates section.

following and unfollowing

To follow the sender of the current tweet, or someone mentioned in a tweet, use control+win+l. If you wish to select someone other than the person that comes up as the first entry, be sure to press down arrow first. Use your screen reader's read current line command to see what is selected. You can also fill in a user name manually.

If at any time you no longer want to get a particular user's tweets in your home buffer, unfollow them with control+shift+win+l. The sender of the current tweet is the default option but you can also enter a different user name manually. You can also block a user from following you, or report their tweet as spam from this dialog.

Blocking and unblocking users

As just mentioned, the unfollow dialog (ctrl+shift+win+l) also contains an option to block a user from following you. You can view a list of users that you have blocked by pressing ctrl+win+backslash. The information that is presented for each user can be customized with a template. See the section on templates for more information. To unblock the selected user, press ctrl+win+delete.

posting updates

post a new tweet

To post a new tweet, press ctrl+win+n. It will bring up a dialogue and place you in an edit field. Just type away. Twitter limits you to 140 characters, so if you go over this limit Twitmonger will make a sound to let you know. (Note: Characters are anything you can type, whether it be a letter, punctuation mark, number, symbol, or space.).

If you're curious to know how many characters you've used up so far, use your screen readers read application title command. It will say something along the lines of "new Tweet - 40 of 140," where 40 is the number of characters you've already used. (Believe me, this feature though small, is a very useful one.)

When you're done writing your sage 140 character remark of wisdom, press enter. You should hear the tweet sent sound, and Twitmonger (via your screen reader) will announce "update posted."

Reply to a tweet

Remember us talking about mentions and replies earlier? Here's where we find out how to make them. When you're reading your list of tweets, and you come across one you want to reply to, use ctrl+win+r. It'll bring up a dialogue very similar to the new tweet dialogue.

Just type your reply, and press enter. Take special notice of your character count after you start typing, as part of your available characters go to showing who you're replying to. As before, checking your title will give you an idea of how many characters you have to work with.

This dialog box also contains a button to mention all users in the selected tweet. This is an easy way to make sure that all of the people involved in a conversation remain in the loop. Please note that the more users you mention in this way, the fewer characters you will have for your actual message.

Post a direct message

To post a direct message, find a tweet from the person you wish to DM, and press ctrl+win+d. The same type of dialogue comes up. (Note, you can only direct message people that follow you. This is a twitter rule, not a limitation of the Twitmonger client. Without this limit, everyone would be flooded with dm spam and that feature would be even more useless than email.)

Deleting a tweet you have posted

It happens to all of us. You reply to the wrong person, or send a public tweet instead of a direct message. Or maybe you simply realize that what you just posted doesn't deserve to see the light of day. If for any reason you wish to delete one of your tweets, simply locate the offending tweet and press control+win+delete.

view a tweet

You can view any tweet by pressing control+win+v to bring up the view tweet dialog. Also in this dialog, there is the retweet checkbox. If you check this and press the ok button, the tweet is posted as a retweet. If unchecked, the current tweet is posted as a regular update. Press cancel if you don't wish to do anything with this tweet.

Other commands for working with tweets

Following are some commands that make your life easier when working with tweets. We plan to add more of these in the future, and if you have any suggestions, be sure to let us know.

Interacting with tweets

There is now an easy way to quickly activate a link that is posted in a tweet. Pressing control+win+enter will interact with the first URL that is mentioned in a tweet. In most cases, the given web page will be opened in your default web browser for you to view. However, if the link points to an audio post that has been recorded with one of the supported audio posting services, or the tweet contains the #audio hashtag, Twitmonger will play the content directly without the need to open any extra windows. By default, Twitmonger will alert you when a tweet links to audio content that you can play within Twitmonger. To stop the audio playback, press control+win+enter again while focused on the same tweet. In adition to q-audio, the service utalized in qwitter,, Twitmonger can currently automatically play posts found on or audioboo. as well as any audio stream or file tagged with the #audio hashtag.

working with favorites

If you come across a tweet that you really appreciate, you can add it to a list of your favorite tweets by pressing alt+win+f. To remove a tweet from your favorites list, press alt+shift+win+f. You can also remove a favorite from within the favorites list with control+win+delete

To bring up a buffer containing your favorites, press control+win+alt+f. To bring up another user's favorites, press control+shift+win+alt+f. This will bring up a dialog for you to select the user who's favorites you wish to view. The first option will be the sender of the current tweet. You can press the down arrow to select any other user mentioned in that tweet. Use your screen reader's read current line command to see what is currently selected. You can also enter a different user name manually. You can dismiss a favorites buffer with control+win+apostrophe.


Retweeting a tweet

If you come across a tweet that you find interesting in some way, you can post it again for your followers to see. This is known as a retweet. Retweets are marked with "RT @username" before the tweet text. To retweet the current tweet, press control+shift+win+r. In the miscellaneous tab of the twitter configuration dialog, You can choose whether you want to add a comment to your retweet. The first setting is recommended. In this mode Twitmonger will ask you each time you press the retweet command. The second mode will assume you want to send the retweet automatically without comment. The third option will simply assume that you want to comment.

If you are adding a comment, the tweet is shown in the retweet dialog so you can edit it at your leasure. Once you're done, press ok and the tweet is posted.

viewing retweets

To view retweets, press control+win+alt+r. This displays a dialog asking you which type of retweets you would like to view. There are 3 options: my friends retweets, my retweets, and my retweets that have been retweeted by friends. These options are pretty self-explanatory. When you have made your selection, press ok. A buffer containing the type of tweets you selected will be created. Note: this is a new feature of twitter, and may still have some bugs. This also means that some other twitter clients have not yet switched to the new method of posting retweets, so you may not see a lot of tweets in this buffer. Only tweets that are posted through Twitmonger without comments will appear in these buffers.

Searching for tweets

The search function of twitter allows you to search for a word or term in publically available tweets across the twittersphere. To begin a new search, press control+win+/. This will bring up a search dialog. If the current tweet contains any hash tags, you can select them by pressing down arrow. Use your screen readers read current line feature to see what is selected. Hashtags are used by people on twitter to make it easier to search for tweets about a given event or topic. For example people attending the 2010 CSun technology conference tagged their tweets with the hashtag #csun10 to make them easy to search for.

After you have typed in your search term, there are a couple more options you can choose. The first is a checkbox that says "persistent search." If checked, this option stores your search results in the current account, so that if you use the same search term ever again from that account, you'll be able to see the previous results. The second checkbox, save search, tells Twitmonger that you want this search to come up in a buffer every time you restart Twitmonger. For searching, each API call can bring up 100 results. The next option sets the number of posts to retrieve during each update, and the default is 100. If this remains at the default, the next option will be the max API calls to use per update of this search. The default will be whatever you set in the default settings tab of the buffer configuration dialog. Click OK, and a search buffer will be created and you will be placed in this buffer. Note that if you create a saved search, Twitmonger will automatically save posts in-account.

Note that these search buffers act just like any other buffer and that they will update as new results come in or if forced to by the force update keystroke. To dismiss a search buffer, or any dismissable buffer, press control+win+apostrophe.

Searching for a user

If you are looking for a particular person on twitter, but do not know their user name, Twitmonger can help you find them. Pressing control+shift+win+/ will bring up the user search dialog. Simply enter the person's real name, and Twitmonger will provide up to 20 accounts that match your search term.

The information that is presented for each user is the same as in the followers and friends buffers, and can be customized with a template. See the section on templates for more information.


How filters work

Filters allow you to search a particular buffer for a keyword or term. To bring up the filter dialogue use ctrl+shift+win+f. You will be focused on the edit box where you can fill in your search term.

If you tab from there, you have two options that customize how your filter will be applied. The first is the list of available fields. Select each field in this list box that you would like the filter to check. The next option is the excluding checkbox. IF you leave it unchecked, it basically acts like a find function. Twitmonger will find all the tweets with your search term in the buffer you're filtering and put them all in a new buffer. However, if you use the excluding checkbox, it will instead filter out all of the matching tweets from your chosen buffer.

The next option is the replace source buffer checkbox. If this is unchecked, the source buffer will remain available along with the filter results. If the replace source buffer checkbox is checked, the original buffer will be replaced by the filter buffer until you dismiss it. This is probably most commonly used in combination with the excluding checkbox. With either setting, you can use ctrl+win+apostrophe to dismiss the buffer when you're done with it. Filters will last until you dismiss the filter buffer.

You can also create several filters at once so they work together. When you are finished setting the rules for the first filter, press the add button to enter your second filter. The dialog contains a list of the filter rules you have set up so far, and you can pres the remove button if you decide you don't want a particular rule.


Real world examples make it clear how powerful filters can be. Here are some common ways that you can mix and match the options to get useful results.

Here's an example of stacking filters. You could set an excluding filter to remove #spymaster from your home buffer, then continue to add another excluding filter to remove automatic tweets about what people are listening to with the #nowplaying hashtag. Now you have a buffer containing everything in your home buffer without things that annoy you. You can add as many filters as you like.

Advanced Filtering with regular expressions

Advanced users may wish to construct more complicated filters. Twitmonger's filtering system has a checkbox which allows you to use regular expressions in your filters to match exactly what you want them to match.

This is a very advanced filtering language which is far beyond the scope of this document, but it is also very well documented on the internet. It is not at all necessary to know anything about this to use filters effectively, but if you are interested you can search wikipedia or google for "regular expressions" for a vast supply of information and examples.


What are lists?

Lists allow you to put various twitter users into a group that you can monitor easily. With Twitmonger, lists will appear in their own buffer. There are 2 kinds of lists, public and private. Public lists, as the name implies, can be seen by anyone, and are useful for letting others see groups of resources or things you find of interest. Private lists on the other hand are only visible to the person that creates them. Some popular uses of lists include grouping family members or friends together in one place, listing a particular type of resource (whether it be a certain type of news, community related information, or something else), or twitter users that share a common interest. It's all up to what you want to do with it.

The List Manager

At the core of lists in Twitmonger is the list manager. It is accessed with alt+win+l, and allows you to view all the lists you've created, as well as any other lists from other users that you subscribe to. The list manager is also where you add, delete, and edit lists, as well as subscribing to lists from other users. There is also a spawn list button, in case you close the buffer for a list and wish to reopen it.

Adding and deleting users from lists

To add/remove a user to/from a list, find their username in a friends or followers buffer or locate a tweet of theirs. Type ctrl+alt+win+l to add the user or ctrl+win+shift+alt+l to remove the user. It will bring up a combo box, where you can edit the username if you wish, then press enter. Next, it will ask you what list you want to add or remove the user from. Use up and down arrows to choose the appropriate list, and press enter.

Viewing lists created by others

You may also wish to follow public lists that other users have created. To do this, press win+alt+shift+l. This will bring up a dialog for you to select the user who's lists you wish to view. The first option will be the sender of the current tweet. You can press the down arrow to select any other user mentioned in that tweet. Use your screen reader's read current line command to see what is currently selected. You can also enter a different user name manually.

At this point, the list manager will open, displaying all of the public lists that person created, as well as other lists that they are subscribed to. Selecting a list and pressing the subscribe button will inform twitter that you wish to follow that list. You will appear in the list of subscribers, and it will appear as one of your lists when you open the list manager with win+alt+l. If you are already subscribed to a list, this button changes to an unsubscribe button. Pressing the spawn button will open a new buffer for the list.

Viewing the members and the subscribers of a list

When you are browsing the buffer for a particular list, you may want to quickly see which users this list contains, or which other users follow this list. Press alt+win+left bracket to get a buffer containing a list of users that subscribe to this list. This is similar to the list of followers for an individual user. Press alt+win+right bracket to get a buffer containing a list of the users in this list. This is similar to seeing who an individual user follows.

The information that is presented for each user is the same as in the followers and friends buffers, and can be customized with a template. See the section on templates for more information.

When viewing the members of a list, You can also remove a user from a list by pressing control+win+delete from this buffer.

Exporting tweets

Twitmonger also supports exporting tweets. As of this release, posts can be exported to plain text files. Other formats may be added later.

Press control+win+e to open the export dialog. In the format tab, press the save as button to open a dialog box to select where you would like to save the file. If you intend to save multiple sets of items, you can select the export more checkbox and the dialog will come back up when the export is complete.

Now press control+tab to select the items tab. The first option is which buffer to export from. The next option allows you to customize how the posts will be exported using a template. The range option has three options. All (bottom to top) will export the entire buffer with the oldest tweets first. All (Top to bottom) will export the entire buffer with the newest tweets first. Be careful using these options with a very large buffer, such as the home buffer. The custom option allows you to specify the range of posts to be exported.

Using the custom option, the next two fields will ask for the index of the first and last post to export. Pressing control+win+space on a post will speak the item number at the end of the tweet, or you can use $index somewhere in your templates.

Once you have set the options, press the OK button to export the selected tweets.


Twitter has a feature that can show you what some of the most popular topics are at any given moment. There is a list of trends for all of twitter, as well as specific lists for trends in certain locations. To bring up a buffer containing the current top trends on twitter worldwide, press control+win+t. To see trends for a specific location, press control+shift+win+t. This will bring up a location selection dialog. First choose whether you want to look up trends for an entire country, or for one town or city. Then press tab to choose a location from a list and press enter to see a buffer with trends for that area. Dismiss the buffer with control+win+apostrophe. Note that these trends are in order with most popular at the top, and when you first pull up the buffer you'll be starting at the bottom.

The public timeline

All tweets posted to twitter are available in the public timeline, with the exception of users who have their tweets protected. You can view a snapshot of the public timeline with control+win+alt+p. This will bring up a buffer with the latest 20 tweets. Note that with the popularity of twitter, tweets are constantly coming into the public timeline by the thousands. Update the buffer with control+win+u for another sample.

Listing followers and friends

To bring up a list of your followers, press control+win+left bracket. Alternatively, to bring up a list of your friends, twitterspeak for people you follow, use control+win+right bracket. Note that these lists may take a while to load, depending on how many friends or followers you have. You can also have Twitmonger keep track of new followers and those who stop following you. Bring up your followers list with control+win+left bracket and wait until the list is loaded. Then press control+win+alt+left bracket. Twitmonger will create a new buffer containing the list. The first time you do this, all of your followers will be reported as new. When you follow these steps in the future, Twitmonger will list who has started or stopped following you.

You may also add the shift key to these commands to view the followers or friends of a different user. This will bring up a dialog where you can select a user. The sender of the current tweet is the first option in this dialog. You can select anyone mentioned in the current tweet by pressing down arrow. Use your screen readers read current line feature to see what is selected. You can enter a username manually as well. With these commands, Each API call can get up to 100 friends or followers. There is an option to set how many will be retrieved, with a default of 100. If this stays at the default, there is an option for the maximum API calls to use. This will start out with the setting you chose in the default settings tab of the buffer configuration dialog. When your done, press ok. This will create a new buffer containing that person's followers or friends. Dismiss the buffer with control+win+apostrophe.

Note: Just like any other buffer, you can use all standard keystrokes for unfollowing/following, replying, direct messaging, etc. on these users.

Note: the extra information spoken about each user can be customized with the friends and followers template. See the section on templates for more information.

Examining your social Network

Once you have brought up both your lists of followers and friends, you can easily do some interesting comparisons of the lists by pressing control+win+alt+right bracket. This gives you the option to see three different aspects of your social network on twitter.

Getting the location of a tweet

Twitter has a feature that allows people to include exact location information with their tweets, and Twitmonger makes it easy to hear this information. If the sender's client is including this geolocation data, simply pressing control+win+g will tell you where the person was when they wrote a given tweet. Pressing control+shift+win+g will display the same information in a text box so that you can review or copy it.

This is a relatively new feature of twitter, and some clients may not support it yet. Also, people can choose not to participate with this feature. Therefore, this will not work with all tweets. By default, Twitmonger will alert you when location information is available.

You also have the option to input latitude and longitude coordinates manually. Press control+win+shift+alt+g and Twitmonger will prompt you for the information. If the current tweet contains geolocation data, those coordinates will be filled in by default. The coordinates you enter will be looked up and the location will be displayed in a text box.

Note that Twitmonger can only read geolocation data provided by others. Twitmonger can not add geolocation data to your tweets.

device notifications

Twitter can also send tweets to your mobile phone via text message, if you have it configured on These are known as device notifications. You can decide who's tweets you'd like to receive on a per-user basis. To change this, find a tweet from the user you'd like to change, and press control+win+shift+d. This will toggle the state of that user's device notifications on. Pressing it again will turn notifications off.

Editing your profile

You can change the information listed in your twitter profile from Twitmonger. Press control+win+shift+p to bring up a dialog where you can change any of the fields in your profile.

Getting Information about a user

Viewing a user's tweets

You may choose to view the individual timeline for any user. Simply press control+win+i. This will bring up the individual buffer dialog. The sender of the current tweet is the first option in this dialog. You can select anyone mentioned in the current tweet by pressing down arrow. Use your screen readers read current line feature to see what is selected. You can enter a username manually as well. By pressing tab, you can choose how many tweets you want to get with each updates. If you select 200 you can also set the max API calls to use per update. Each API call can get 200 tweets. By befault this setting matches what you set in the default tab of the buffer configuration dialog. When your done, press ok. This will create a new buffer containing that person's latest tweets. Dismiss the buffer with control+win+apostrophe.

Determining a user's relationship to yourself

You can easily find out what kind of relationship exists between yourself and another user on Twitter. Press control+win+alt+semicolon on a message to have Twitmonger announce the type of relationship which exists between you and that user. You will hear who is following whom once the information is retrieved. Note that this operation requires one API call.

You can also press control+win+alt+shift+semicolon to check the relationship between any two users. A dialog will come up where you can indicate which two users to check. You can choose between your own username, the sender of the current tweet or anyone mentioned in the tweet. You can also type in any other username you wish.

Viewing a user's profile

There are 2 ways of accessing the information listed in another user's Twitter profile.

Muting Twitmonger

You can easily configure exactly what new content you want Twitmonger to notify you about. Each account and buffer in Twitmonger has it's own independent mute setting. When a buffer is muted, automatic updates will not play any sounds or say anything when new items come in. Checking for updates manually will provide spoken feedback without sounds when the buffer is muted.

You can choose to only mute particular buffers. Press ctrl+alt+win+m from within a buffer you want to mute. Also, each buffer's tab within the Buffer configuration Dialog Contains a mute checkbox for that buffer. Muting a buffer only mutes notifications of incoming tweets for the buffer. It does not mute other sounds such as when you exceed the max tweet length or reach the top or bottom of a buffer. If you have used previous versions of Twitmonger, think of this as a mute received mode that is now buffer-specific.

You can mute an entire account by pressing ctrl+win+m. There is also a account mute checkbox, which can be found in the sounds tab of the account configuration dialog, accessible with ctrl+win+o. Unlike the buffer mute, this option mutes all sounds for this account.

It is also possible to globally mute all Twitmonger accounts. To do so, so as to hear no sounds at all from the program, press control+shift+win+m.

Configuring the twitter account

From within a Twitter account, you can open the Twitter configuration dialog by pressing control+win+o. This dialog box controls configuration options that only effect the current twitter account. We generally suggest leaving these settings at the defaults until you have used Twitmonger for a while, but we'll briefly touch on each of them in the sections below. Many of these options are discussed more fully in appropriate places later in this document. This dialog is divided into sections, or tabs. Press control+tab and control+shift+tab to navigate between the various sections. Press the ok button when you are finished.

Sounds tab

The first option on this tab allows you to choose a soundpack. Twitmonger only comes with one soundpack, but people have contributed many others which are available for download at Soundpack Central. When you download a soundpack, unzip it to the sounds folder where you have installed Twitmonger. If you kept the defaults, you would unzip the soundpacks to c:\program files\Twitmonger\sounds.

The account mute checkbox allows you to easily mute all sounds and spoken update notifications for this account. You can also leave this box unchecked and control the mute status for each buffer separately.

Templates tab

The options in this tab allow you to configure a few of Twitmonger's templates. These concepts are described later, and you do not need to touch these options when setting up a twitter account for the first time.

Most templates are set in the buffer configuration dialog. The templates in this tab are those that either effect newly created buffers or simply can not be set separately for each buffer. As a convenience, this tab contains a button to modify existing buffer templates, which simply opens the buffer configuration dialog for you.

There are also templates that control the format of outgoing replies and retweets. It is strongly recommended that you leave these settings at their default, since these are the standard twitter conventions and should not be changed.

Miscellaneous Tab

First we have DM safe mode. This is the one option you may wish to change your first time. If checked, this will make it so that when you reply to a direct mesage it will reply as a direct message, rather than a public reply. Also, it will stop you from retweeting direct messages.

When The next option is turned on, Twitmonger will ask you for confirmation when you delete tweets or direct messages that you have sent.

The option labeled perform standard actions with home/end keys" will change the behavior of those keys. With this turned on, pressing them will jump to the start/end of the current line rather than the start or end of the entire item you are writing.

The next option allows you to select your prefered URL shortener. When posting tweets, Twitmonger gives you the option to use one of several URL shortening services to make web addresses shorter and give you more room to type.

The next setting controls the way retweets are sent. See the section on retweets for the details of these options.

The last option on this tab is reply to self. If unchecked, Twitmonger will not allow you to post a reply (You'll learn about those later) to yourself.

The template system

It is easy to customize how Twitmonger announces information. The format is controlled by templates. Templates are strings of text that contain instructions for Twitmonger on what to speak or copy to the clipboard. These instructions begin with the $ sign. In the simplest and most common usage, you just place variables in the text which Twitmonger replaces with the appropriate information. The variables you can use are described in the following tables. There are also conditional templates, but these are described later and are not necessary to understand in order to start using templates. If for some reason you wish to have Twitmonger actually use $ in your templates, you would indicate this by writing $$. Braces are also special characters in templates, so to use one of these you would indicate it by writing ${{ or $}}.

Most of the templates are configured for each buffer in the buffer configuration dialog, accessible with control+alt+win+o. The templates tab of the twitter configuration dialog, accessible with control+win+o, contains templates that are used when creating new buffers, and a few for formatting tweets you send.

templates for formatting tweets

The templates for specifying how Twitmonger formats tweets are set in the buffer configuration dialog, accessible with control+win+alt+o. The tab for each buffer has a set of two template options. The speech output and the format of tweets copied to the clipboard can be set separately. The twitter configuration dialog, accessible with control+win+o, also contains a new generic buffer template that will be applied to any new buffers as well as a template for search results. The following table lists variables that you can use to customize the output.

Variable Description
$time The exact time the tweet was posted.
$date The date the tweet was posted.
$when An Estimate of how long ago the tweet was sent.
$name The name of the person who sent the tweet. Note that $name is unavailable in the search template. This is a limitation of twitter.
$screen_name The screen name of the user who posted the tweet|
$message The text of the tweet.
$from The name of the twitter client that was used to post the current tweet, or web if it was posted directly on
$index A number representing the tweet's location in the buffer, with 1 being the newest.|
$total The total number of tweets in the current buffer. This is most useful in conjunction with $index. For example, $index of $total might say 30 of 165.
$geo Indicates whether or not geolocation data are available for a tweet. Best used as part of a conditional template (see below).
$dm Indicates that a tweet is a direct message. It's mainly used for the sent buffer as part of a conditional template in combination with $rcpt_name
$rcpt_name The recipient of a direct message. It's mainly used with the sent buffer as part of a conditional template with $dm.
$nl Will create a new line in the output. Useful in clipboard templates.

Templates for formatting user information

There are also templates that specify what is spoken when Twitmonger lists information about users. These are located in the templates tab of the twitter configuration dialog. The new followers/friends buffer template determines what is spoken when viewing lists of friends or followers. The user info template determines the items spoken when control+win+semicolon is pressed. The following table lists the available variables for these templates. In addition to those mentioned below, $index, $total, and $nl also work as previously described.

Variable Description
$name Will be replaced with the user's real name.
$screen_name Will be replaced with the user's screen name on twitter.
$location Will be replaced with any location information the user specified in their profile.|
$bio Will be replaced with the users bio.|
$url Will be replaced with the address of a user's web site if one was set.|
$followers_count Will be replaced with the number of followers a user has.
$friends_count Will be replaced with the number of people a user is following.|
$tweets_count Will be replaced with the number of tweets a user has posted since joining Twitter.|
$when Estimates how long ago a user joined twitter.
$date Will be replaced with the date on which the user joined twitter.
$time Will be replaced with the exact time that a user joined twitter. Best used right after $date.
$local_time Will be replaced with the current time in the user's local time zone.
$local_date Will be replaced with the date in the user's local time zone.
$last_tweet_when Estimates how long ago a user last posted a tweet. This is only available in the friends and followers template.|
$last_tweet_time Gives the exact time of a user's last tweet. This is only available in the friends and followers template.|
$last_tweet_date Gives the date of the user's last tweet. This is only available in the friends and followers template.|
$protected Indicates whether a user has protected their tweets.
$notifications Indicates whether you have turned device notifications on for a user

Conditional Templates

Conditional templates allow you to have more control over what Twitmonger speaks based on the contents of the variables you use. Twitmonger's default templates already contain some useful ones. If you don't understand the following discussion or aren't interested in conditionals, you can ignore them since their use is optional.

The format for a conditional template looks like this:


The {if_false} part of the definition can be left out if you don't want Twitmonger to say anything if the condition is not met.

We will provide Some examples to better demonstrate how this works. The simplest use of conditionals simply tells Twitmonger what to say if a variable is set to true or false. The sent buffer's default format uses the following conditional to determine if a tweet is a direct message and speak the recipient if it is.

$if(dm){DM to $rcpt_name:}

In this case, this part of the template says nothing if the message is a normal tweet since the {if_false} section was left out.

A similar example is the handling of geolocation data. Since most tweets don't contain this information, the default template flags the ones that do by using the following conditional.


Now let's look at an example using both {if_true} and {if_false} statements. You could put the following conditional in your user info or followers/friends template to indicate whether a given user has protected his or her tweets:

$if(protected){tweets are protected}{tweets are public}

Conditionals can also use instructions known as relational operators. Note that you may need to raise your screen reader's punctuation level or read a character at a time to hear this part correctly. One possible usage would be to have Twitmonger speak a different message depending on how many people follow a given user. This sample conditional could be used in the user info or followers/friends template to point out those users with a significant following.

$if(followers_count >= 1000){popular}

Relational operators are far more powerful than this. A complete discussion of potential uses is beyond the scope of this section. Here are a list of the different relational operators you can use:

Operator meaning
== Equal to
< Less than
<= Less than or equal to
> Greater than
>= Greater than or equal to
<> or != Not equal to

Customizing Twitmonger

The Keyboard manager.

All of the commands listed in this document can easily be customized using Twitmonger's keyboard manager. Press ctrl+win +k to bring up a list of commands available in the current account. The execute keystroke button will act just as if you had pressed the keystroke yourself. You can press the edit button to change the assigned keystroke. Editing a command brings up a series of checkboxes to select which modifier keys are used, and a place to type the key you want to use. There are also buttons to delete commands from the list or add commands you previously deleted.

Controling Twitmonger with less keys

If you will be reading a very large number of tweets, or you are using Twitmonger for a long period of time, you can temporarily lock the ctrl and windows keys with alt+win+k. This enables the most common Twitmonger functions to be performed with a single key. Repeat the keystroke to deactivate the mode. Alternatively, it will be automatically deactivated when you switch accounts or close Twitmonger.

Twitmonger's main configuration dialog

You can press control+shift+win+o to bring up Twitmonger's main configuration dialog. This dialog controls configuration options that are used throughout the program. We suggest leaving them at the defaults until you have used Twitmonger for a while. This dialog is divided into sections, or tabs. Press control+tab to move through the sections. Press the ok button when you are finished.

language tab

In this tab you can select which language you wish Twitmonger's messages to be in. Several languages are available, and if yours isn't and you're willing to translate, it can be added.

Speech tab

The first item on this tab, speech output, is set to auto. There will rarely ever be any reason to change this, as Twitmonger auto-detects your screen reader. If it doesn't detect a supported screen reader, or you're not running one, it will automatically use whatever microsoft speech synthesizer you have selected in your control panel. If for some reason you don't want to use a screen reader even though you're running one, you can instead choose SAPI.

The next three options are pretty self explanitory; they allow you to change the rate, volume and voice used by Microsoft speech if you choose to use SAPI with Twitmonger.

The final option on this tab allows you to enable or disable Twitmonger's speech recognition function. You can also toggle this by pressing shift+win+s.

Navigation tab

The first option on this tab controls how far Twitmonger jumps through items when using control+win+page up and page down to move by a percentage.

The next 2 options control how far Twitmonger jumps through items when using control+win+shift+page up and page down to move by time. The first box determines how many hours Twitmonger should jump, and the second determines how many minutes Twitmonger should jump. For example, if the hours box was set to 1, and the minutes box was set to 5, Twitmonger would jump 1 hour and 5 minutes forward or back depending on which command you issued.

The last option here is the undo stack size option. It determines the number of undo operations you can do with control+win+z. For example, if the value of this box is set to 100, you can undo the last 100 commands.

Braille tab

There is currently one option in this tab. The braille spoken text checkbox determines whether Twitmonger's braille support will be used.

Miscellaneous tab

The first option is self-explanatory. If you don't want to be prompted before exiting Twitmonger, uncheck the Show Confirmation checkbox here.

The option labeled "perform standard actions with home/end keys" will change the behavior of those keys. With this turned on, pressing them will jump to the start/end of the current line rather than the start or end of the entire item you are writing.

Changing Twitmonger's default key assignments

All of the keystrokes used in Twitmonger can be easily changed. Press control+win+k to access the keystroke manager. Every keystroke that is available will be listed here. You can change a keystroke's assignment with the edit button, or remove it entirely with the delete button. If you remove a function, you can later assign it again with the add button.

You can quickly perform any Twitmonger function from within the keystroke manager. Just find the command you wish to run and press the execute function button.

Quitting Twitmonger

If for some reason you wish to close Twitmonger, use ctrl+win+f4. It'll bring up a confirmation dialog, if the program is configured to do so. If not, Twitmonger will immediately exit.

Portable mode

If you run Twitmonger with -p or --portable on the command line or from a shortcut, it will run in portable mode, meaning that any files it reads and rights will be kept in the Twitmonger program's current directory, making it ideal to use on a thumb drive. Here is an example of how to set this up.

Let's assume you have Twitmonger installed in the default location on your C drive. And let's assume your thumb drive is drive E. Windows may have assigned a different letter to your thumb drive.

Copy your c:\Program Files\Twitmonger folder to e:\Twitmonger.

Next, copy all the contents of %appdata%\Twitmonger to e:\Twitmonger as well.

Once that is done, anytime you want to run Twitmonger in portable mode from your thumb drive, you simply do start, run, then type the following:

e:\Twitmonger\Twitmonger.exe -p

Technical Support

Twitter API issues

If you suddenly start having problems using Twitter when it previously worked normally, chances are very good that the issue is with the twitter API itself, not the Twitmonger client. The fact that the twitter web site may be working normally does not decrease the likelyhood that the API for external applications may be experiencing issues. You can check the twitter status page to determine if there are known issues with the twitter API. Below are some conditions that have commonly been reported in the past. There is no need to report these, as there is nothing that Twitmonger developers can do about them.

I get a message that states that the program can not start because the log file could not be accessed.

On operating systems starting with windows vista, people sometimes get this message the first time they run Twitmonger. There is a simple fix for this.

Locate the installed Twitmonger icon and press shift+f10 or the applications key if you have it. Arrow down to run as administrator and press enter. A user account control dialog will appear asking if you would like to allow the application access to your computer. Answer yes to this prompt and Twitmonger should start as normal.

Note: You should only have to do this once.

When reviewing tweets, the time that is announced is incorrect.

For Twitmonger to announce the correct posting time for tweets, your time zone must be set correctly on and on your computer. Here's how to check your time zone settings.

To set the time zone on twitter, sign in to your account and select the settings link. On that page, you will find several options, including one for choosing your time zone. Once you have selected your time zone and pressed the save button, twitter may prompt you to enter your password again to change settings.

On your computer, open the windows control panel and select date and time. There you will be able to set your computer's date, time and time zone. Setting the correct time is not sufficient, since the wrong time will still be announced if your time zone is set incorrectly.

When writing a tweet, it is difficult to review what I've written using jaws.

There is a known conflict between Twitmonger and the jaws scripts for the McTwit application. Jaws is associating Twitmonger dialog boxes with the McTwit scripts, a combination that does not work. At this time, the only known solution is to remove the McTwit scripts from your system. Mctwit is still very accessible without them.

I have a question/comment/concern that's not covered in this readme.

We have tried our best to cover all the features of Twitmonger in this readme. However, if there is a question that you have which is not covered here, please feel free to contact one of the developers. Here's a list:

Change Log

0.5 Alpha

0.4 Alpha

0.3 Alpha

0.2 Alpha

0.1 Alpha

Known Issues

The following are known bugs at the time of release, and are already reported to us and are being actively worked on and will make it into the next release.


Thanks go out to the developers of the no-longer-developed Qwitter client, from which the Twitmonger core derives quite a bit of its code. Thanks also go out to Bitbucket for providing a free and wonderful service, our repository for the source code, the issue tracker, and space to store our binary releases.