/examples/capsule/README.txt

 1== capsule.py ==
 2
 3capsule.py beat matches parts of several songs into a single mp3. Given a transition duration, and an inter-transition duration, the program searches for the best order, the closest transition patterns, and apply beat alignment, time-stretching and crossfading into a single audio stream output. The result is a music collage with smooth transitions acting as the glue. Note that beat alignment is independent of downbeats during pattern search: it is optimal in the sense of timbral pattern matching, which may be perceptually tricky in the case of different styles. Therefore downbeats (first beat of the bar) don't necessarily align. Transitions can start anywhere in the track, and for any duration: it is up to the developer to apply additional constraints on top of the core engine of capsule to create less predictable and more interesting results. 
 4
 5An earlier version of Capsule powers http://thisismyjam.com.
 6
 7
 8== Usage ==
 9
10Usage: capsule.py [options] <list of mp3s>
11
12Options:
13  -h, --help            show this help message and exit
14  -t TRANSITION, --transition=TRANSITION
15                        transition (in seconds) default=8
16  -i INTER, --inter=INTER
17                        section that's not transitioning (in seconds)
18                        default=8
19  -o, --order           automatically order tracks
20  -e, --equalize        automatically adjust volumes
21  -v, --verbose         show results on screen
22  -p PDB, --pdb=PDB     dummy; here for not crashing when using nose
23
24
25== Examples ==
26
27After installing your Echo Nest API Key, try the following in your terminal:
28$ python capsule.py ../music/BillieJean.mp3 ../music/EverythingIsOnTheOne.mp3
29It'll combine into capsule.mp3, 8 seconds (default) of BillieJean.mp3 with 8 seconds of EverythingIsOnTheOne.mp3 via 8 seconds (default) of beat-matched transition.
30
31To change the transition and inter transition paramaters use the options -t and -i, e.g.,
32$ python capsule.py -t 4 -i 20 ../music/BillieJean.mp3 ../music/EverythingIsOnTheOne.mp3
33makes a quicker 4-second transition with longer 20-second inter-transition excerpts of the tracks.
34Note that every track that doesn't fit the parameter constraints will simply be rejected from the mix.
35
36Option -o allows you to automatically order the tracks, currently by tempo:
37$ python capsule.py -o ../music/BillieJean.mp3 ../music/EverythingIsOnTheOne.mp3
38plays EverythingIsOnTheOne.mp3 first.
39
40Option -v allows you to see details about what is going on during computation.
41$ python capsule.py -o -v ../music/BillieJean.mp3 ../music/EverythingIsOnTheOne.mp3
42displays the following time of action, action name, time parameters, duration, and title.
43
4400:00	  Fade in	    100.421	-> 100.671	 (0.250)	Everything Is On The One
4500:00	  Playback	    100.671	-> 108.671	 (8.000)	Everything Is On The One
4600:08	  Crossmatch	108.671	-> 232.107	 (7.502)	Everything Is On The One -> Billie Jean
4700:15	  Playback	    232.107	-> 240.297	 (8.190)	Billie Jean
4800:23	  Fade out	    240.297	-> 246.297	 (6.000)	Billie Jean
49
50Note that every capsule starts with a 250 ms quick fade in and ends with a 6-second fade out.
51
52With option -e you can equalize the relative volume between tracks.
53$ python capsule.py -o -e -v ../music/BillieJean.mp3 ../music/EverythingIsOnTheOne.mp3
54pushes the gain of the first track by 33% and the second track by 10%
55
56Vol = 133%	Everything Is On The One
57Vol = 110%	Billie Jean