Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 240 lines (144 sloc) 8.411 kb
94ecb00 @holman Crack the README
holman authored
1 # Play
e52f52c @holman
holman authored
2
94ecb00 @holman Crack the README
holman authored
3 Play is an employee-powered iTunes-based client-driven distributed music server
4959fa1 @holman More of the README
holman authored
4 for your office. Also it can prepare your taxes.
e52f52c @holman
holman authored
5
94ecb00 @holman Crack the README
holman authored
6 ## Background
81d7904 @holman link to API docs
holman authored
7
94ecb00 @holman Crack the README
holman authored
8 Did you know that listening to music while you work produces better and faster
9 code? It's true. It's in a README.
e52f52c @holman
holman authored
10
94ecb00 @holman Crack the README
holman authored
11 We listen to music constantly at GitHub. So I wrote Play. Initially it was a
12 modest shell-oriented music server, but we've since grown it to quite the setup:
e52f52c @holman
holman authored
13
7cb1c1d @holman Welcome to Play Next
holman authored
14 ![Play at GitHub](http://cl.ly/1l3o0p0K3O1r0C2U3a3Z/play.png)
4959fa1 @holman More of the README
holman authored
15
16 We have employees all over the world, but Play lets us all listen to the same
17 music as if we were all in the office together. This has actually made a big
18 impact on our culture.
19
20 ## The Setup
21
22 ### OS X
23
24 Play is built for the Mac. We use a Mac Mini.
25
26 ### iTunes
27
28 Play is **iTunes-based**. That means we can let iTunes do what it's good at and
29 manage the state of our music. We use **iTunes DJ** to handle the main Play
30 queue, specifically because it emulates what Play does: provide a smart playlist
31 neverending songs.
32
33 ### The Stream and Speakers
34
35 We use [Nicecast][nicecast] to take the audio stream from iTunes and deliver it
36 to our client apps so everyone can stream from their platform of choice.
37
38 We also use iTunes' built-in AirPlay support to stream to multiple speakers
39 across our office network.
40
41 ### Web
42
43 The heart of Play is the web app. This is effectively an API to access and
44 control your iTunes library over the web. The app also handles music upload:
45 just drag your files to the browser window, then they'll get uploaded and
46 indexed in iTunes. No complex file sharing and office VPN setups necessary.
47
944336b @maddox add pusher info and better description of clients
maddox authored
48 ### Pusher
49
50 Play's realtime notification is powered by [Pusher](http://pusher.com/). Pusher
51 allows Play to provide realtime updating to any client that cares. This includes
52 the site as well as Play clients. Clients will be updated in realtime as Play cycles
53 through songs as well as when new songs get queued.
54
4959fa1 @holman More of the README
holman authored
55 ### API
56
57 We primarily drive Play through [Campfire][campfire], the chat service we use
58 internally at GitHub. Most Play interactions happen through the API rather than
59 the web interface, and the API is actually a superset of the functionality
60 available through the web.
61
62 ## Installation
63
64 ### Setup
65
66 Play has a lot of moving parts, but we've tried to simplify installation as much
67 as we could.
68
69 First, clone down the repository:
70
acb18e7 @maddox fixed urls
maddox authored
71 git clone https://github.com/play/play.git && cd play
4959fa1 @holman More of the README
holman authored
72
73 Next, you need to run the bootstrap process, which will verify that we can talk
74 to iTunes, that you have all of your settings set up correctly, and will guide
75 you through the configuration setup:
76
cf95511 @holman Standardize with GitHub's `script/bootstrap` paradigm
holman authored
77 script/bootstrap
4959fa1 @holman More of the README
holman authored
78
79 During the bootstrap process you'll be asked to enter your [Pusher][pusher]
80 credentials. This is optional, but it'll let you get realtime updates to your
81 Play queue. It's like the future. Websockets and shit.
82
9d7fe54 @maddox Be a little clearer about starting iTunes and the DJ playlist before sta...
maddox authored
83 ### Starting It Up
84
85 Open up iTunes and start playing music from the iTunes DJ playlist. It's important that you **do this first**. **Yes** the DJ playlist is required.
86
106b248 @maddox iTunes Match jacks things up. Explain this more in the README - addresse...
maddox authored
87 **iTunes Match is mostly NOT supported. See more details on this at the bottom of this README.**
88
26ae7bc @wfarr Update README to add note about making sure iTunes is playing
wfarr authored
89 At this point, you should be ready to play:
4959fa1 @holman More of the README
holman authored
90
91 rake start
92
93 That'll start the server up on [localhost:5050](http://localhost:5050).
94
6aac6d1 @holman play.coffee
holman authored
95 ### Hubot Integration
96
97 We use Play primarily through Campfire, through Hubot. There's a
98 [play.coffee](https://github.com/github/hubot-scripts/blob/master/src/scripts/play.coffee)
a455e36 @roryokane README grammar fix – "to" -> "for"
roryokane authored
99 file that you can drop into your Hubot installation for integration with Play.
6aac6d1 @holman play.coffee
holman authored
100
a7f4abb @maddox added API auth details to README
maddox authored
101 ### API/Client Auth
102
103 Each user on Play has a unique auth `token`. They will give this `token` to each Play client for it to make requests on their behalf.
104
6818678 @abdinoor Fixing a typo in the README
abdinoor authored
105 In addition to these unique tokens, each Play installation also has its own unique system wide auth `token`. This can be used to auth and masquerade as any user on the system. When using this system wide `token`, a `login` must be provided in the request so Play knows what user the request is masquerading as. This is essentially how [Hubot](https://github.com/github/hubot) will communicate with Play.
a7f4abb @maddox added API auth details to README
maddox authored
106
107 Both of these styles tokens can be included as a **header** or as a **query param**.
108
109 ### User Token
110
111 When using a user's `token`, only the `token` needs to be included. It can be added to the request in the header or as a query param.
112
113 #### Header
114
115 "Authorization: 5422fd"
116
117 #### Query Param
118
119 ?token=5422fd
120
121 ### System Token
122
123 When using a system token, a `login` needs to be added to the request in addition to the system `token` added by the means described above. It can be added to the request in the header or as a query param.
124
125 #### Header
126
127 "X-PLAY-LOGIN: maddox"
128
129 #### Query Param
130
131 ?login=maddox
132
133
4959fa1 @holman More of the README
holman authored
134 ### Clients
135
136 Part of the fun with Play is getting it everywhere: in your office, on your
137 desktop, and on your phone. Once you get Play set up correctly, you'll need to
32cc244 @maddox not really true anymore
maddox authored
138 install [Nicecast][nicecast].
4959fa1 @holman More of the README
holman authored
139
140 The following clients exist for Play:
141
86f04fe @maddox added screenshots to client section of README
maddox authored
142 #### OS X
143
144 [play/play-cocoa](https://github.com/play/play-cocoa)
145
146 <a href="https://github.com/play/play-cocoa">![](http://f.cl.ly/items/3J2U1Z2x033R3p1I1J0b/play-item.png)</a>
147
148 #### iOS
149
150 [play/play-cocoa](https://github.com/play/play-cocoa)
151
152 <a href="https://github.com/play/play-cocoa">![](http://f.cl.ly/items/1Z1W3P351q2V1m2v3n12/play-ios-iphone.png)</a>
153 <a href="https://github.com/play/play-cocoa">![](http://f.cl.ly/items/2Z0O09320f142y3x163q/play-ios-ipad.png)</a>
154
155 #### Windows
156
157 [play/play-windows](https://github.com/play/play-windows)
158
159 <a href="https://github.com/play/play-windows">![](http://cl.ly/3D0u3N102O1D0m1g3B1Y/Image%202012.04.19%202:35:54%20AM.png)</a>
160
161
162 #### Android
163
164 [play/play-android](https://github.com/play/play-android)
165
c318f5b @kevinsawicki Update Android application screenshot
kevinsawicki authored
166 <a href="https://github.com/play/play-android">![](http://img.skitch.com/20120429-rq3sgm8fbbbxwisep7rbsedj6h.png)</a>
86f04fe @maddox added screenshots to client section of README
maddox authored
167
fb805b4 @maddox now playing screen shot
maddox authored
168 #### Now Playing on TV
4959fa1 @holman More of the README
holman authored
169
170 We also have a TV at the office with the currently-playing song. This doesn't
171 require any setup; just point your TV's browser at the main Play instance and
172 the TV interface should show up as long as the screen ratio is 16:9
173 (ie, 720p or 1080p).
174
fb805b4 @maddox now playing screen shot
maddox authored
175 ![](http://cl.ly/1c0D0d0Y1a1K0S3s0N0m/Image%202012.04.19%204:46:51%20PM.png)
176
4959fa1 @holman More of the README
holman authored
177 ## Technical Details
178
179 ### AppleScript
180
181 The entire Play + iTunes bridge is handled via AppleScript. Play talks to
182 AppleScript, AppleScript talks to iTunes, and we make it dance.
183
184 ### The Web is the API
185
186 The web app is a simple, straightfoward Sinatra app. State that we can't stash
187 in iTunes is persisted through **Redis**.
188
189 The entire web app is just a thin client over the API, which is delivered
190 through JSON. We only really deliver one HTML page: the main root page. All data
191 on that page is populated via JSON requests. This means we can focus on one API
192 and use it for both the web and for every other client.
193
194 The frontend is built with SCSS, CoffeeScript, Mustache, Pusher, and jQuery. All
195 assets are compiled and delivered via Sprockets.
196
197 ### Native Clients
198
67d6a45 Fix Pusher link
Paul Betts authored
199 Native clients use [Pusher](http://pusher.com/) to be updated in realtime. They will show
944336b @maddox add pusher info and better description of clients
maddox authored
200 what is currently playing, and with some clients, what is queued. All clients are built
201 to consume the Shoutcast stream.
4959fa1 @holman More of the README
holman authored
202
106b248 @maddox iTunes Match jacks things up. Explain this more in the README - addresse...
maddox authored
203 ## iTunes Match
204
205 Like many people have experienced on iOS with apps that use your music library, iTunes Match royally
206 screws this up. iTunes does nothing to differentiate songs that are actually available on disk, and those
207 that would need to be pulled down first by Match in order to play them.
208
209 This screws up Play, just as it screws up iOS apps that naively (not their fault) attempt to play something
210 out of the music library that is actually only available via Match.
211
212 This can hopefully be addressed in the future. For now, skip Match.
213
4959fa1 @holman More of the README
holman authored
214 ## Contributing
215
216 We'd love to see your contributions to Play. If you'd like to hack on Play,
217 you'll likely want to run Play in development mode:
218
219 shotgun
220
221 That will reload the code on each page request. You can hit the server on
222 [localhost:9393](http://localhost:9393).
223
224 You can run the tests with:
225
226 rake
227
228 Fork the project, make your commits, then send a Pull Request.
229
230 ## Play
231
232 Play was written by [Zach Holman](https://twitter.com/holman) and shaped by the
233 fine ladies and gentlemen at [GitHub](https://github.com/github). We've also
8038a0d @holman typo
holman authored
234 benefited from a lot of hard work from our
acb18e7 @maddox fixed urls
maddox authored
235 [contributors](https://github.com/play/play/contributors).
4959fa1 @holman More of the README
holman authored
236
58bfb72 @holman Update URLs
holman authored
237 [nicecast]: http://rogueamoeba.com/nicecast/
238 [campfire]: http://campfirenow.com/
239 [pusher]: http://pusher.com/
Something went wrong with that request. Please try again.