Real-time sonification and visualization of Twitter data.
More information at: http://ccrma.stanford.edu/groups/tweetdreams/
You'll need a machine with the following:
- Python (only 2.6 or 2.7 have been tested)
- Python's
virtualenv
module installed - Java
- Chuck
Note: the code should be cross-platform, but it has only been tested in OS X (10.5 and 10.6)
- Get the code
> git clone git@github.com:jorgehatccrma/TweetDreams.git
or download it from https://github.com/jorgehatccrma/TweetDreams/zipball/master
- Initialize the Virtual Environment
Go to the root folder of the downloaded code and type
> source init.sh
(the containing folder will become a virtual python environment and all the dependencies will be downloaded and installed in this isolated virtual environment)
- Configuring a performance
-
In a performance/installation, is possible to run all three parts (visual, audio, tweet server) in the same machine, but they can also run in different machines (or any combination). The only change required to run TweetDreams in different machine configurations is to specify the ip addresses of the involved machines.
-
Local Term: this is the term, usually a hash-tag (e.g. #TweetDreams), that will be treated with particular prominence during the performance. This term is specified as an argument passed to the launch script (see next section)
-
Search terms: tweets containing any of these terms will also be displayed during the performance. To change them, edit the
search_terms.txt
file in the root folder. Is also possible to specify a different file (see next section). -
IP addresses: If different parts of TweetDreams are run in different machines, each one needs to know the IP addresses where the others are running.
-
Initial Tweets: Is possible to pre-define a set of "fake" tweets to be displayed at the beginning of the performance. These are defined in
initial_tweets.txt
. -
Banned terms: For some performances we have been asked to remove some offensive words. The words declared in the
offensive_words.txt
file will be replaced with as many asterisks (*) as letters in the word.
- Run it
Read this before you try to run it! Since June, 2013, the Twitter API requires oAuth authentication (the old username/password method doesn't work any more). Since the source code is open, but our twitter dev accounts are not, the required consumer_key
, consumer_secret
, access_token
, access_secret
are not included in the source code. Given that scenario, to run TweetDreams you will need to get your own twitter dev account, and get these keys and tokens (it is free and easy, just go to https://dev.twitter.com/ and follow the instructions). Once you get your keys and tokens, you will need to add them to src/python/twt.py
(search for those terms, defined with empty strings and replace them accordingly).
To run TweetDreams, run the startDreaming.py
script from the root folder:
> python startDreaming.py -l \#YourHashTag -j 192.168.1.2
Note: the backslash (\) is only necessary to escape the pound (#) symbol. If you don't want a pound symbol in you local_term, then you need to omit the \.
The above command and options will run the Python and Chuck server in the local machine and the Java visualizer in a remote machine (that's the default setting). If you want to run everything in the local machine, you can run the script with the following options (by default all IP addresses are set to localhost
):
> python startDreaming.py -l \#music -T -S -V
Note if you do this, the visualizer will probably cover your terminal with a black screen. You can (should) bring the terminal to the forefront to debug in case there's any issue.
The above example will launch the tweets server (python) and sound (chuck) server locally (localhost) and will send OSC messages to the visualizer (java) app running at 192.168.1.2.
There are many other arguments that can be passed to this script. For a complete list run:
> python startDreaming.py -h
- Interactions
1/2
: available waveforms for next tree3/4
: available melodies for next tree5/6
: the timing for the next tree7/8
: the mode for the next tree (currently I think should stay in one mode)9/0
: increase/decrease the dry level for all sounds
g/h
: inc/dec min global queue time (by 100 msec)j/k
: inc/dec max global queue time (by 100 msec)z,x,v,b,n,m
: (bottom row of keyboard) add/remove search terms
i/o
: zoom in/outw/a
: horizontal plane spina/d
: vertical plane spin
You can also control the following parameter using a MIDI device:
- zoom
- spin-x
- spin-y
- root-length
- tree-length
- text-size
- "trace"
- drag (viscosity)
For details dig into src/java/src/MidiManager.java
.
- Luke Dahl (lukedahl@ccrma.stanford.edu)
- Jorge Herrera (jorgeh@ccrma.stanford.edu)
- Carr Wilkerson (carrlane@ccrma.stanford.edu)