play / play

play ► — your company's dj

Play

Play is an employee-powered iTunes-based client-driven distributed music server for your office. Also it can prepare your taxes.

Background

Did you know that listening to music while you work produces better and faster code? It's true. It's in a README.

We listen to music constantly at GitHub. So I wrote Play. Initially it was a modest shell-oriented music server, but we've since grown it to quite the setup:

We have employees all over the world, but Play lets us all listen to the same music as if we were all in the office together. This has actually made a big impact on our culture.

The Setup

OS X

Play is built for the Mac. We use a Mac Mini.

iTunes

Play is iTunes-based. That means we can let iTunes do what it's good at and manage the state of our music. We use iTunes DJ to handle the main Play queue, specifically because it emulates what Play does: provide a smart playlist of neverending songs.

The Stream and Speakers

We use Nicecast to take the audio stream from iTunes and deliver it to our client apps so everyone can stream from their platform of choice.

We also use iTunes' built-in AirPlay support to stream to multiple speakers across our office network.

Web

The heart of Play is the web app. This is effectively an API to access and control your iTunes library over the web. The app also handles music upload: just drag your files to the browser window, then they'll get uploaded and indexed in iTunes. No complex file sharing and office VPN setups necessary.

Pusher

Play's realtime notification is powered by Pusher. Pusher allows Play to provide realtime updating to any client that cares. This includes the site as well as Play clients. Clients will be updated in realtime as Play cycles through songs as well as when new songs get queued.

API

We primarily drive Play through Campfire, the chat service we use internally at GitHub. Most Play interactions happen through the API rather than the web interface, and the API is actually a superset of the functionality available through the web.

Installation

Setup

Play has a lot of moving parts, but we've tried to simplify installation as much as we could.

First, clone down the repository:

git clone https://github.com/play/play.git && cd play

Next, you need to run the bootstrap process, which will verify that we can talk to iTunes, that you have all of your settings set up correctly, and will guide you through the configuration setup:

script/bootstrap

During the bootstrap process you'll be asked to enter your Pusher credentials. This is optional, but it'll let you get realtime updates to your Play queue. It's like the future. Websockets and shit.

Starting It Up

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.

iTunes Match is mostly NOT supported. See more details on this at the bottom of this README.

At this point, you should be ready to play:

rake start

That'll start the server up on localhost:5050.

Hubot Integration

We use Play primarily through Campfire, through Hubot. There's a play.coffee file that you can drop into your Hubot installation for integration with Play.

API/Client Auth

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.

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 will communicate with Play.

Both of these styles tokens can be included as a header or as a query param.

User Token

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.

Header

"Authorization: 5422fd"

Query Param

?token=5422fd

System Token

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.

Header

"X-PLAY-LOGIN: maddox"

Query Param

?login=maddox

Clients

Part of the fun with Play is getting it everywhere: in your office, on your desktop, and on your phone. Once you get Play set up correctly, you'll need to install Nicecast.

The following clients exist for Play:

OS X

play/play-cocoa

iOS

play/play-cocoa

Windows

play/play-windows

Android

play/play-android

Now Playing on TV

We also have a TV at the office with the currently-playing song. This doesn't require any setup; just point your TV's browser at the main Play instance and the TV interface should show up as long as the screen ratio is 16:9 (ie, 720p or 1080p).

Technical Details

AppleScript

The entire Play + iTunes bridge is handled via AppleScript. Play talks to AppleScript, AppleScript talks to iTunes, and we make it dance.

The Web is the API

The web app is a simple, straightfoward Sinatra app. State that we can't stash in iTunes is persisted through Redis.

The entire web app is just a thin client over the API, which is delivered through JSON. We only really deliver one HTML page: the main root page. All data on that page is populated via JSON requests. This means we can focus on one API and use it for both the web and for every other client.

The frontend is built with SCSS, CoffeeScript, Mustache, Pusher, and jQuery. All assets are compiled and delivered via Sprockets.

Native Clients

Native clients use Pusher to be updated in realtime. They will show what is currently playing, and with some clients, what is queued. All clients are built to consume the Shoutcast stream.

iTunes Match

Like many people have experienced with iOS apps that use your music library, iTunes Match royally screws this up. iTunes does nothing to differentiate songs that are actually available on disk, and those that would need to be pulled down first by Match in order to play them.

This screws up Play, just as it screws up iOS apps that naively (not their fault) attempt to play something out of the music library that is actually only available via Match.

This can hopefully be addressed in the future. For now, skip Match.

Contributing

We'd love to see your contributions to Play. If you'd like to hack on Play, you'll likely want to run Play in development mode:

shotgun

That will reload the code on each page request. You can hit the server on localhost:9393.

You can run the tests with:

rake

Fork the project, make your commits, then send a Pull Request.

Play

Play was written by Zach Holman and shaped by the fine ladies and gentlemen at GitHub. We've also benefited from a lot of hard work from our contributors.

play's Issues

Convert hubot/play.js to hubot/play.coffee

This is where we'll find the shrimp.

indexing + dupes

Play just stops indexing after 5 seconds and prints out 9 of these messages
id3v2 tag not fully parsed: tag size is > 50_000_000

Any particular idea why?

Also, it might be because of the indexing error, I have tons of dupes in play's database and library. Tho none in iTunes
This is bugging me off, any ideas?

null reference

mainly my fault, but if your public profile isn't filled out, OAuth will put a user entry into the db with null for everything except id and login. Applications works fine but when you load the profile get gravatar fails since email is nil.

user.rb

def gravatar_id
Digest::MD5.hexdigest(email)
end

hubot what's the volume

return current volume

move ~/.play.yml to config/

do it

screenshot

The new play looks so fucking good. Show it.

Starring via browser broken?

Trying to star songs on OS X Lion using Chrome or Safari results in an endless spinner, and it can't seem to tell which songs have previously been starred.

Starring via API works (ie Hubot will add line to the table), it's just the browser end.

Let Foreman do the work

I think this could simplify bin/play, and you can launch web and server at the same time. Don't detach the music server perhaps.

Support for m4a

I just realized after an hour that Play doesn't add my new songs to the library because they are lossless audio.

Like I said before, not really a ruby guy but I gladly open a PR if you could give me some pointers.

bin/setup

it'll be rad!

Auto-migrate

We know the current schema version, we know what we need to get to... auto-migrate these fools.

Download an album

Download an album, bro. Trickier, but MORE IMPORTANT.

Download a file

API endpoint to download/stream a file. Specifically for now playing, although probably could work for any of it, really.

index fails when non-US-ASCII filename encountered

pair@harkness:~/dev/play(master+)$ bin/play index
/Users/pair/dev/play/lib/play/library.rb:20:in `split': invalid byte sequence in US-ASCII (ArgumentError)
    from /Users/pair/dev/play/lib/play/library.rb:20:in `fs_songs'
    from /Users/pair/dev/play/lib/play/library.rb:30:in `import_songs'
    from bin/play:41:in `block in index_music'
    from bin/play:41:in `fork'
    from bin/play:41:in `index_music'
    from bin/play:62:in `<main>'

mysql2 adapter

Zach,

This really isn't an issue with play, but it was a frustration I had to deal with when installing.

establish_connection’: Please install the mysql2 adapter:gem install activerecord-mysql2-adapter` (no such file to load — >active_record/connection_adapters/mysql2_adapter) (RuntimeError

In order to correct the issue I had to run the following command:

sudo install_name_tool -change libmysqlclient.18.dylib /usr/local/mysql/lib/libmysqlclient.18.dylib ~/.rvm/gems/ruby-1.9.2-p290/gems/mysql2-0.3.7/lib/mysql2/mysql2.bundle

Thought it might be useful for someone.

Nice application. Off the topic, I've loved your recent banter with Scott Hanselman and Rob Conery. Excellent post on the matter.

undefined method `closed?' for nil:NilClass

I am getting this error on the callback page for the github oauth flow.

Use votes for "play something I'd like" if stars aren't available

It looks like play_stars only uses stars and not votes at all. If a user has requested songs but hasn't actually starred anything, this causes a 500 error as of fcb91e1ba and causes hubot to crash if you ask it to play something you like.

Might be pragmatic just to avoid the 500 error for now. Arguably, requests != liked songs.

Please add 1.9 support

Tried to run bin/setup on 1.9.2-p290 and 1.9.3-p0. Neither worked (both complained about SystemTimer, which I believe only works on MRI 1.8).

NoMethodError when going to /artist/something

Hey,

I managed to install play on Ubuntu 11.4, replacing afplay by mpg123, now I hear the music I added to my Music folder but I can't add a particular album because when I want to play for example some "Ace of Base" I receive this error :

NoMethodError at /artist/Ace+of+Base
undefined method `songs' for nil:NilClass
file: app.rb location: GET /artist/* line: 110

I'm completely new to Ruby (i know Python though), node.js etc.. but I'm very interested in this particular project and I would like to learn but I confess that I did not manage to get rid of this error. It doesn't seem that there is an error in app.rb.

Thank you for your help, I hope that i will manage to get this very cool program running!

@edit :

I finally could access to one of the artist of my library putting %20 instead of + for the spaces. It should be cool though if play didn't show such a nasty error when an artist is not found.

My gravatar's not showing up

http://REDACTED/defunkt

Where's it get the email address from? My Campfire user has a Gravatar, but for some reason my Play user does not.

Assuming I just don't know which damn email I'm using with Play, maybe displaying your email address on the profile page would be helpful.

mysql2 adapter...yet again

I have the same error as this fella https://github.com/holman/play/issues/28
I cannot resolve the issue, here is my output:
https://gist.github.com/1578706
Can anyone help me with this, I feel a bit stranded...

Play Queue - Play States

Currently, when a song begins to play, it's removed from the queue. It'd be rad if it was given a class of 'Currently Playing' and if a song has just finished playing, it can have a 'Recently Played' state. Then you could style those states in the web view and give depth to the queue.

★

Shit needs to have ★s. How can this project not have ★s. ★s are pretty fucking important.

• Create an API endpoint to star the currently-playing song
• Create an API endpoint to play 10 from your starred song list
• Maybe show these in the web interface

You can call `playlists` on any song

Rad.

Fix `play -s`

Because it ain't work

yajl segmentation fault on setup

All good installing it using bin/setup up to the end:

  + Migrating your database.
/Users/ralf/.rvm/gems/ruby-1.8.7-p352/gems/yajl-ruby-1.0.0/lib/yajl/yajl.bundle: [BUG] Segmentation fault
ruby 1.8.7 (2011-06-30 patchlevel 352) [i686-darwin11.3.0]    

bin/setup-darwin: line 123: 25705 Abort trap: 6           bin/play migrate 2>&1 > /dev/null

Tried reinstalling 1.8.7 with RVM, no luck though, any idea? I'm no ruby man so this is though.

Web server pages not displaying any songs

All the pages on the web server do not display any songs. If I queue manually (/add/id) the songs play, but the web interface still shows no songs in the queue. The user profile pages do not show an avatar or any songs. The web server process does not show any issues and all the web pages produce a HTTP Status 200.

Clean up README

• Reduce the play commands to a table
• review office integrations
• update current status
• link to screencast

"Enter" to enter OAuth details

Let it pause on the directions with the URLs, and then press enter to open the URL.

Search on the web interface isn't very good

There should be better search. It should be more fuzzy. For example "gambino" doesn't match childish gambino.

Error on building native extensions

I keep getting this error when doing gem install play

ERROR:  Error installing play:
ERROR: Failed to build gem native extension.

    /usr/local/bin/ruby extconf.rb
creating Makefile

make
gcc -I. -I/usr/local/include/ruby-1.9.1/x86_64-darwin10.7.0 -I/usr/local/include/ruby-1.9.1/ruby/backward -I/usr/local/include/ruby-1.9.1 -I. -D_XOPEN_SOURCE -D_DARWIN_C_SOURCE   -fno-common -D_XOPEN_SOURCE=1 -fno-common -pipe  -o system_timer_native.o -c system_timer_native.c
In file included from system_timer_native.c:8:
/usr/local/include/ruby-1.9.1/ruby/backward/rubysig.h:14:2: warning: #warning rubysig.h is obsolete
system_timer_native.c: In function ‘install_ruby_sigalrm_handler’:
system_timer_native.c:211: error: ‘rb_thread_critical’ undeclared (first use in this function)
system_timer_native.c:211: error: (Each undeclared identifier is reported only once
system_timer_native.c:211: error: for each function it appears in.)
system_timer_native.c: In function ‘restore_original_ruby_sigalrm_handler’:
system_timer_native.c:217: error: ‘rb_thread_critical’ undeclared (first use in this function)
make: *** [system_timer_native.o] Error 1


Gem files will remain installed in /usr/local/lib/ruby/gems/1.9.1/gems/SystemTimer-1.2.3 for inspection.
Results logged to /usr/local/lib/ruby/gems/1.9.1/gems/SystemTimer-1.2.3/ext/system_timer/gem_make.out

Any solutions?

When last.fm fails to find album art, ugliness ensues

Formalizing this into a proper issue. There are already two branches which solve them which are blocked on aesthetic grounds. #57 became #59 due to a preference to have a placeholder image instead of falling back to text. #59 needs a better placeholder image, but I'm not capable of making one.

playcount

vote.count is being used to populate the playcount on the show_song page.

show_song.rb

def plays
@song.votes.count
end

I would assume this would be

def plays
@song.playcount || 0
end

mysql2 error on install?

I had been running play without issue on my laptop, but decided to move it to our work server (mac running 10.7.2 with nothing installed)

I installed mysql and then attempted to install play using the system ruby, but always run into the following:

  + Migrating your database.
/Library/Ruby/Gems/1.8/gems/activerecord-3.1.1/lib/active_record/connection_adapters/abstract/connection_specification.rb:71:in `establish_connection': Please install the mysql2 adapter: `gem install activerecord-mysql2-adapter` (dlopen(/Library/Ruby/Gems/1.8/gems/mysql2-0.3.7/lib/mysql2/mysql2.bundle, 9): Library not loaded: libmysqlclient.18.dylib (RuntimeError)
  Referenced from: /Library/Ruby/Gems/1.8/gems/mysql2-0.3.7/lib/mysql2/mysql2.bundle
  Reason: image not found - /Library/Ruby/Gems/1.8/gems/mysql2-0.3.7/lib/mysql2/mysql2.bundle)
    from /Users/cwd/play/lib/play/app.rb:29
    from /Library/Ruby/Gems/1.8/gems/sinatra-1.3.1/lib/sinatra/base.rb:1273:in `configure'
    from /Users/cwd/play/lib/play/app.rb:25
    from ./bin/../lib/play.rb:18:in `require'
    from ./bin/../lib/play.rb:18
    from bin/play:6:in `require'
    from bin/play:6

Stars and API responses

"I like this" should return:

• What's currently playing
• Maybe others who have ⭐d this song

Order of tracks when queuing up albums

When queuing albums the order of the album is important. Right now play orders them by alphabetic order (at least, it seems like it).

Link @holman in README to Twitter page

This is no way major, but in README.md @holman points to http://twitter.com and not to http://twitter.com/holman

Why does index fork?

Indexing can take a long time, but I'm not sure I understand the rationale behind forking it.

Play Queue - Refresh

Is it possible to make the web ui refresh after events like skipping and completion of a song, so that it updates the view?

Do a screencast

AUDIO VIDEO DISCO

"Hubot I like this song" "Hubot play my favorites"

I'd be cool to basically be able to star a song from campfire, then have hubot play all of them back when requested.

bin/backup

Purely because I know I'll never back up the work mini often.

hubot remove x from the queue

fuck a color garth brooks

Migrate the database in bin/setup

Seems like this should be done in the setup script. And probably the index step too.

Travis

Add Travis to this project to avoid #18.

I'm pretty sure "Download this album" sends me a Zipped version of a 500 page

You know, for all of those 100% legally downloadable albums. http://[GITHUB'S PLAY SERVER]/album/111/download for example.

favicon

play-next should have a rad favicon and apple-touch-icon.png for the iPad view.

Songs repeated

My library is indexed 3 times, yeah, 3 times, no more, no less.

Play by album

Add an album view would be mucho nifty.

Don't block on song refresh

It's not fun.