Voicebox Cloud API

These are the resources available to view and manipulate the songs, queues, lights, and other features of the Voicebox Cloud package.

These features are available for Voicebox, as well as our partner organizations with Voicebox Cloud enabled.

See the overview documentation for details about response codes, error handling, organizations, etc.

Resource Overview

Login

Profile

Songs

Song Favorites

Queue

Current Song

Audio

Lights

Popups

Play History


POST /api/version/login.format

Login to the Voicebox API by email, which will or find or create a new profile if it does not already exist, and associate the current session with the profile. This is necessary for some features, such as keeping favorite songs, playlists, and more as Voicebox grows.

Parameters

  • session (optional)
    This is normally generated by the client, and should be specified
    When unspecified, returns a new session to be used
    See overview documentation for more information about sessions and login

  • email (required)
    A valid email address

Examples

To login a user, letting the server generate a new session ID

POST /api/v1/login?email=test@email.com

To login a user, where the client chooses a random session ID

POST /api/v1/login?email=test@email.com&session=12345678-1234-1234-1234-123456abcdef

Example Response

{
    "session": "12345678-1234-1234-1234-123456abcdef",
    "email": "test@email.com",
    "handle": "test",
    "color": "#00BCB5",
    "hide_handle_in_queue": false
}

GET /api/version/profile.format

Get the profile for the currently logged-in user.

Parameters

  • session (required)
    The user must be logged-in

Examples

To get a logged-in user’s profile, given their session ID

GET /api/v1/profile?session=12345678-1234-1234-1234-123456abcdef

Example Response

{
    "session": "12345678-1234-1234-1234-123456abcdef",
    "email": "test@email.com",
    "handle": "test",
    "color": "#00BCB5",
    "hide_handle_in_queue": false,
    "birth_year": 1975,
    "birth_month": 11,
    "birth_day": 22
}

PUT /api/version/profile.format

Set values for the currently logged-in user. Any unspecified values are left unchanged.

Parameters

  • session (required)
    The user must be logged-in

  • handle (optional)
    This is used to identify the user in the queue and when posting popups

  • color (optional)
    This is used to identify the user in the queue and when posting popups
    Must be a valid hexadecimal color value like #4455FF (the # is optional)

  • hide_handle_in_queue (optional)
    When set, any songs added to the queue by this user are anonymous

  • birth_year (optional)
  • birth_month (optional)
  • birth_day (optional)
    Be a member of the birthday club!
    This is optional, but if set, both birth_month and birth_day must be present.
    birth_year is always optional. We won’t pry.

Examples

To set a logged-in user’s handle, to be shown on-screen

PUT /api/v1/profile?session=12345678-1234-1234-1234-123456abcdef&handle=rickroller

Example Response

{
    "session": "12345678-1234-1234-1234-123456abcdef",
    "email": "test@email.com",
    "handle": "rickroller",
    "color": "#00BCB5",
    "hide_handle_in_queue": false,
    "birth_year": null,
    "birth_month": null,
    "birth_day": null
}

GET /api/version/songs.format

Access songs available at Voicebox.

The intended usage is to page through songs by artist, title, popularity, or recent additions, much as you would browse songs in a printed song book.

Parameters

  • by (optional)
    one of artist, title, popularity, or recently_added
    defaults to artist

  • prefix (optional)
    when unspecified, returns results across all songs
    use character ‘$’ to browse all songs that begin with a non-alphabetic character

  • language (optional)
    when unspecified, returns all languages

  • tag (optional)
    return songs with a specific tag, e.g. to filter by genre
    See the song tags resource below for a list of available tags
    when unspecified, returns results unfiltered by tag

  • page (optional)
    defaults to 1

  • per_page (optional)
    defaults to 50
    maximum is 1000

Examples

To get the first page of the English song book by title, use

GET /api/v1/songs?by=title&language=English

To get the second page, in JSON format, use

GET /api/v1/songs.json?by=title&language=English&page=2

To get just songs by title that start with ‘d’, use

GET /api/v1/songs?by=title&language=English&prefix=d

To get the list of most popular songs, use

GET /api/v1/songs?by=popularity

To get the most popular duets, use

GET /api/v1/songs?tag=Duet&by=popularity

To get the third page of songs by artist that start with ‘depeche’, with a page size of 2, use

GET /api/v1/songs?by=artist&language=English&prefix=depeche&page=3&per_page=2

Example response

{
  "by": "artist", 
  "prefix": "depeche", 
  "language": "English", 
  "tag": null, 
  "page": 3, 
  "per_page": 2, 
  "total_pages": 10, 
  "total_entries": 20, 
  "songs": [ 
    { 
      "id": 56831, 
      "title": "Everything Counts", 
      "artist": "Depeche Mode", 
      "language": "English", 
      "play_count": 107, 
      "added_on": "2009-06-16", 
      "tags": [ 
        "80s" 
      ] 
    }, 
    { 
      "id": 56830, 
      "title": "Home", 
      "artist": "Depeche Mode", 
      "language": "English", 
      "play_count": 28, 
      "added_on": "2009-06-16", 
      "tags": [ 
        "90s" 
      ] 
    } 
  ] 
}

GET /api/version/songs/id.format

Access information about a single song by ID.

Parameters

None

Examples

To get the JSON information for Don’t Stop Believin’, use

GET /api/v1/songs/67277.json

To get the same information using a cross-domain JSONP call, use

GET /api/v1/songs/67277.json?callback=mycallback

Example Response

{ 
  "song": { 
    "id": 67277, 
    "title": "Don't Stop Believin'", 
    "artist": "Journey", 
    "language": "English", 
    "play_count": 8145, 
    "added_on": "2013-11-04", 
    "tags": [ 
      "80s", 
      "Fan Videos" 
    ] 
  } 
}

GET /api/version/songs/search.format

Search songs by title or artist.

Parameters

  • query (required)
    Search terms to find in the title or artist of a song
    Returns all matches, across artist and title
    Putting quotes the query will do an exact match (but case-insensitive) on artist or title

  • language (optional)
    when unspecified, returns all languages

  • page (optional)
    defaults to 1

  • per_page (optional)
    defaults to 50
    maximum is 1000

Examples

To get the first page of results searching for ‘Elvis’, use

GET /api/v1/songs/search?query=Elvis

To get the second page, use

GET /api/v1/songs/search?query=Elvis&page=2

To get only English language songs with the term ‘Elvis’, use

GET /api/v1/songs/search?query=Elvis&language=English

Example Response

{ 
  "query": "journey", 
  "language": null, 
  "tag": null, 
  "page": 1, 
  "per_page": 2, 
  "total_pages": 13, 
  "total_entries": 26, 
  "songs": [ 
    { 
      "id": 71885, 
      "title": "Journey To The Past", 
      "artist": "Anastasia", 
      "language": "English", 
      "play_count": 26, 
      "added_on": "2014-05-06" 
    }, 
    { 
      "id": 638, 
      "title": "Sentimental Journey", 
      "artist": "Day, Doris", 
      "language": "English", 
      "play_count": 43, 
      "added_on": "2008-10-31" 
    } 
  ] 
}

GET /api/version/songs/roulette.format

Get a random selection of songs, weighted toward the most popular.

Parameters

  • language (optional)
    when unspecified, returns all languages

  • tag (optional)
    return songs with a specific tag, e.g. to filter by genre
    See the song tags resource below for a list of available tags
    when unspecified, returns results unfiltered by tag

  • from_top (optional)
    return songs from the top N most popular songs
    defaults to 3000

  • per_page (optional)
    defaults to 10
    maximum is 1000

Examples

To get a random page of results, use

GET /api/v1/songs/roulette

To get a random page of results from the top 100, use

GET /api/v1/songs/roulette?from_top=100

To get random Rap songs, use

GET /api/v1/songs/roulette?tag=Rap

Example Response

{
  "language": null,
  "tag": "Rap",
  "per_page": 2,
  "total_entries": 539,
  "songs": [
    {
      "id": 72246,
      "title": "I'm Out",
      "artist": "Ciara & Nicki Minaj",
      "language": "English",
      "play_count": 48,
      "added_on": "2014-11-25",
      "tags": [
        "Pop",
        "Rap",
        "Divas"
      ]
    },
    {
      "id": 69399,
      "title": "Look At Her Go",
      "artist": "T-Pain feat Chris Brown",
      "language": "English",
      "play_count": 3,
      "added_on": "2012-03-12",
      "tags": [
        "Rap"
      ]
    }
  ]
}

GET /api/version/songs/languages.format

Get available languages, and information about how many songs are available in each language.

Parameters

None

Examples

To get all available languages

GET /api/v1/songs/languages

Example Response

{ 
  "languages": [ 
    { 
      "language": "English", 
      "song_count": 15030, 
      "artist_count": 4410 
    }, 
    { 
      "language": "Spanish", 
      "song_count": 2516, 
      "artist_count": 606 
    }
  ] 
}

GET /api/version/songs/tags.format

Get available tags for songs, grouped by category. Tags are how we indicate genre, duets, etc.

Parameters

None

Examples

To get song tags

GET /api/v1/songs/tags

Example Response

{ 
  "categories": [ 
    { 
      "category_name": "Genres", 
      "tags": [ 
        { 
          "name": "Country", 
          "song_count": 522 
        }, 
        { 
          "name": "Disco", 
          "song_count": 76 
        }
      ] 
    }, 
    { 
      "category_name": "Decades", 
      "tags": [ 
        { 
          "name": "90s", 
          "song_count": 392 
        }, 
        { 
          "name": "80s", 
          "song_count": 401 
        }
      ] 
    }
  ] 
}

GET /api/version/songs/stats.format

Get statistics for songs, such as the top played songs and artists.
Also includes information about recently played songs, with breakdowns by day and week.

Parameters

None

Examples

To get song statistics

GET /api/v1/songs/stats

Example Response

{ 
  "total_songs_played": 1326100, 
  "total_songs_available": 67251, 
  "top_songs": [ 
    { 
      "id": 67277, 
      "title": "Don't Stop Believin'", 
      "artist": "Journey", 
      "language": "English", 
      "play_count": 6273 
    }
  ], 
  "top_artists": [ 
    { 
      "artist": "Beatles, The", 
      "play_count": 14829 
    }
  ], 
  "top_songs_today": [], 
  "total_songs_today": 0, 
  "top_songs_this_week": [
    { 
      "id": 67277, 
      "title": "Don't Stop Believin'", 
      "artist": "Journey", 
      "language": "English", 
      "play_count": 46 
    }
  ], 
  "total_songs_this_week": 6727, 
  "latest_song_additions": [ 
    { 
      "id": 72525, 
      "title": "Invincible", 
      "artist": "Clarkson, Kelly", 
      "language": "English", 
      "added_on": "2015-06-12" 
    }
  ], 
  "updated_at": "2015-06-24T03:55:36.185Z" 
}

GET /api/version/songs/favorites.format

Get songs that have been favorited by a logged-in user.

Parameters

  • session (required)
    The user must be logged-in

  • page (optional)
    defaults to 1

  • per_page (optional)
    defaults to 50
    maximum is 1000

Examples

To get a logged-in user’s favorite songs

GET /api/v1/songs/favorites?session=12345678-1234-1234-1234-123456abcdef

Example Response

{
    "page": 1,
    "per_page": 50,
    "total_pages": 1,
    "total_entries": 2,
    "songs": [
        {
            "id": 68250,
            "title": "Beautiful, Dirty, Rich",
            "artist": "Lady Gaga",
            "language": "English",
            "play_count": 9,
            "added_on": "2014-01-07",
            "favorite": true
        },
        {
            "id": 56746,
            "title": "Just Can't Get Enough",
            "artist": "Depeche Mode",
            "language": "English",
            "play_count": 7,
            "added_on": "2015-05-23",
            "favorite": true,
            "tags": [
                "80s"
            ]
        }
    ]
}

POST /api/version/songs/favorites.format

Add a song to save as a favorite. If the song already a favorite for the user, no changes will be made, and the added property in the response will be false.

Parameters

  • session (required)
    The user must be logged-in

  • song_id (required)
    The song you love to sing!

Examples

Add Don’t Stop Believin’ as a favorite song

POST /api/v1/songs/favorites?session=12345678-1234-1234-1234-123456abcdef&song_id=67277

Example Response

{
    "song_id": 67277,
    "added": true
}

DELETE /api/version/songs/favorites.format

Remove a song from your favorites.
If the song is not a favorite for the user, no changes will be made, and the removed property in the response will be false.

Parameters

  • session (required)
    The user must be logged-in

  • song_id (required)
    The song you used to love, and now it’s just been overplayed!

Examples

Remove Don’t Stop Believin’ from a user’s favorites

DELETE /api/v1/songs/favorites?session=12345678-1234-1234-1234-123456abcdef&song_id=67277

Example Response

{
    "song_id": 67277,
    "removed": true
}

GET /api/version/queue.format

Get the song queue for a room.
Returns information about all queued songs, as well as the currently playing song.

Parameters

  • room_code (required)
    The 4-letter code displayed in the room at Voicebox
    Without this code, clients are not able to access the queue

Examples

To get the queue for a room, given that you know the 4-letter code, use

GET /api/v1/queue?room_code=HSCL

Example Response

{
    "room_code": "HSCL",
    "current_song": {
        "song_id": 68250,
        "play_id": "G-Test-6c4008b3e6c4-1435717763903-2",
        "title": "Beautiful, Dirty, Rich",
        "artist": "Lady Gaga",
        "duration": 170000,
        "position": 30000,
        "paused": false,
        "pitch_shift": 0,
        "audio_channels": "stereo",
        "message": "jenny",
        "message_color": "#00BCB5"
    },
    "volume": 75,
    "songs_queued": 1,
    "queue": [
        {
            "index": 0,
            "song_id": 69001,
            "play_id": "G-Test-6c4008b3e6c4-1435717770940-3",
            "title": "Summerboy",
            "artist": "Lady Gaga",
            "duration": 242865,
            "message": null,
            "message_color": null
        }
    ]
}

POST /api/version/queue.format

Add one or more songs to the queue for a room.

Parameters

  • room_code (required)
    The 4-letter code displayed in the room at Voicebox
    Without this code, clients are not able to access the queue

  • song_id (required)
    The numeric song id, typically found by browsing or searching for songs
    This may be a comma-separated list of song ids, to add multiple songs at once

  • to (optional)
    Either a play_id or an index, indicating the new destination in the queue
    If a play_id is used, then the song will be moved to the position of the given play_id
    The index may be negative, indicating a relative position from the end
    defaults to -1, adding the song to the end of the queue

  • allow_duplicate (optional)
    A boolean value, indicating whether adding a song should be checked
    against the songs already in the queue, to prevent consecutive songs with the same song_id.
    Adding the same song in a non-consecutive position is always allowed.
    defaults to false, which prevents adding back-to-back songs

  • message (optional)
    A message that will be displayed in the queue next to the song.
    Note that when a logged-in user adds a song, they will have their handle displayed,
    and providing an explicit message will override the handle in that case.

  • message_color (optional)
    Set the color for the message.
    Should be a standard web format like #1122FF.
    Defaults to #999999 (gray)

Examples

To add Don’t Stop Believin’ to the queue, use

POST /api/v1/queue?room_code=HSCL&song_id=67277

To add 3 songs at once to the queue, use

POST /api/v1/queue?room_code=HSCL&song_id=101,102,103

To add a song to the top of the queue, to be played next after any currently playing song, use

POST /api/v1/queue?room_code=HSCL&song_id=101&to=0

Using curl, from the command-line, this can be accomplished with
curl -X POST -d "" "http://voiceboxkaraoke.com/api/v1/queue.json?room_code=HSCL&song_id=67277"

Example Response

{
    "index": 3,
    "song_id": 67277,
    "play_id": "G-Southeast-6c4008b3e6c4-1435717896331-4",
    "title": "Don't Stop Believin'",
    "artist": "Journey",
    "duration": 268128
}

The index in the response indicates the position the song was added to the queue.
A value of -1 means that it will immediately begin playing as the current song.
Values greater than or equal to 0 correspond to positions in the queue.


DELETE /api/version/queue.format

Delete either a specific song, or all songs, from the queue for a room.
Note, this does not stop the currently-playing song. It only removes upcoming songs.

Parameters

  • room_code (required)
    The 4-letter code displayed in the room at Voicebox
    Without this code, clients are not able to access the queue

  • from (optional)
    Either a play_id or an index, indicating a specific entry from the queue to delete
    If not supplied, deletes the entire queue
    The index may be negative, indicating a relative position from the end
    If from is a play_id that refers to the current song, it will skip the current song

Examples

To delete just a specific song, using a play_id, use

DELETE /api/v1/queue?room_code=HSCL&from=G-Test-28cfe91dc4e7-1415156264149-1

To delete the song that is next in the queue, but keep all of the others, use

DELETE /api/v1/queue?room_code=HSCL&from=0

To delete the song that was most recently added to the queue, use

DELETE /api/v1/queue?room_code=HSCL&from=-1

To clear the entire queue, use

DELETE /api/v1/queue?room_code=HSCL

POST /api/version/queue/reorder.format

Reorder songs in the queue for a room.

Parameters

  • room_code (required)
    The 4-letter code displayed in the room at Voicebox
    Without this code, clients are not able to access the queue

  • from (required)
    Either a play_id or an index, indicating a specific entry from the queue to move
    The index may be negative, indicating a relative position from the end

  • to (optional)
    Either a play_id or an index, indicating the new destination in the queue
    If a play_id is used, then the song will be moved to the position of the given play_id
    The index may be negative, indicating a relative position from the end
    defaults to 0, moving the song to the top of the queue

Examples

Each example assumes a queue with play_ids: G-XXX-1, G-XXX-2, G-XXX-3, G-XXX-4

To move a song to the top of the queue, using a play_id of G-XXX-3,
resulting in: G-XXX-3, G-XXX-1, G-XXX-2, G-XXX-4

POST /api/v1/queue/reorder?room_code=HSCL&from=G-XXX-3

To move a song to the second position in the queue, using a play_id of G-XXX-3,
resulting in: G-XXX-1, G-XXX-3, G-XXX-2, G-XXX-4

POST /api/v1/queue/reorder?room_code=HSCL&from=G-XXX-3&to=1

To move the most recently added song to the top of the queue,
resulting in: G-XXX-4, G-XXX-1, G-XXX-2, G-XXX-3

POST /api/v1/queue/reorder?room_code=HSCL&from=-1

To swap the top two songs in the queue,
resulting in: G-XXX-2, G-XXX-1, G-XXX-3, G-XXX-4

POST /api/v1/queue/reorder?room_code=HSCL&from=0&to=1

POST /api/version/current_song/skip.format

Skip the currently playing song in a room.

Parameters

  • room_code (required)
    The 4-letter code displayed in the room at Voicebox
    Without this code, clients are not able to access the current song

Example

POST /api/v1/current_song/skip?room_code=HSCL

POST /api/version/current_song/restart.format

Rewinds and starts playing the currently playing song from the beginning.

Parameters

  • room_code (required)
    The 4-letter code displayed in the room at Voicebox
    Without this code, clients are not able to access the current song

Example

POST /api/v1/current_song/restart?room_code=HSCL

POST /api/version/current_song/pause.format

Pauses the currently playing song in a room.

Parameters

  • room_code (required)
    The 4-letter code displayed in the room at Voicebox
    Without this code, clients are not able to access the current song

Example

POST /api/v1/current_song/pause?room_code=HSCL

POST /api/version/current_song/resume.format

Resumes playing the currently playing song in a room, if it was previously paused.

Parameters

  • room_code (required)
    The 4-letter code displayed in the room at Voicebox
    Without this code, clients are not able to access the current song

Example

POST /api/v1/current_song/resume?room_code=HSCL

PUT /api/version/audio.format

Controls the audio for the currently playing song in a room.
Setting the volume is persistent, but pitch_shift and channels will be reset when the current song ends.
Note, the audio information is returned as part of the queue response.

Parameters

  • room_code (required)
    The 4-letter code displayed in the room at Voicebox
    Without this code, clients are not able to access the current song

  • volume (optional)
    An integer value from 0 to 100

  • pitch_shift (optional)
    An integer value from -12 to 12
    The number of semitones to adjust the pitch
    1 shifts up by a semitone, -1 down by a semitone, 12 by an octave, etc.
    A value of 0 turns off pitch adjustment

  • channels (optional)
    One of: stereo, left, or right
    Some karaoke videos encode the voice on either the left or right channels
    Setting to left will play only the left channel through both speakers
    Setting to stereo will play normally

Examples

To set the volume to the max, use

PUT /api/v1/audio?room_code=HSCL&volume=100

To mute the audio, use

PUT /api/v1/audio?room_code=HSCL&volume=0

To adjust the pitch down a whole step, and play only the right channel through both speakers, use

PUT /api/v1/audio?room_code=HSCL&pitch_shift=-2&channels=right

To return the pitch shift and audio channels to their default, use

PUT /api/v1/audio?room_code=HSCL&pitch_shift=0&channels=stereo

PUT /api/version/lights.format

Set the lighting levels and effects in a room.
Note, the lighting information is returned as part of the queue response.

Parameters

  • room_code (required)
    The 4-letter code displayed in the room at Voicebox
    Without this code, clients are not able to access the lights

  • mode (optional)
    An integer value
    0 - Bright lights
    1 - Medium lights
    2 - Low lights

  • effects (optional)
    A boolean value, indicating whether the lighting effects should be turned on or off
    In most rooms, this controls the mirror ball

Examples

To turn on the mirror ball, given that you know the 4-letter code, use

PUT /api/v1/lights?room_code=HSCL&effects=1

To set a low lighting level, use

PUT /api/v1/lights?room_code=HSCL&mode=2

To turn off the mirror ball, and raise the lights to a bright level, use

PUT /api/v1/lights?room_code=HSCL&mode=0&effects=0

POST /api/version/popups.format

Show a popup message on-screen in a room. This requires a logged-in session.
Each popup will be shown with the logged-in user’s handle.
The handle defaults to the first part of the email address for the user’s profile.
Note, there is currently no way to get the displayed popups.

Parameters

  • session (required)
    See the description above about sessions
    This session must be logged-in

  • room_code (required)
    The 4-letter code displayed in the room at Voicebox
    Without this code, clients are not able to access popups

  • text (required)
    A text message to display. Have fun!
    Limited to 90 characters

Examples

To show “You rock!” on screen, use (replacing the session as appropriate, of course)

POST /api/v1/popups?session=12345678-1234-1234-1234-123456abcdef&room_code=HSCL&text=You%20rock!

GET /api/version/plays/history.format

Get the play history for the current user. This does not require a logged-in session. However, with a login, your history will be persistent across visits to Voicebox.

Parameters

  • session (required)
    See overview documentation for more information about sessions and login

  • page (optional)
    defaults to 1

  • per_page (optional)
    defaults to 50
    maximum is 1000

Examples

To get the play history for a logged-in user

GET /api/v1/plays/history?session=12345678-1234-1234-1234-123456abcdef

Example Response

{
    "session": "12345678-1234-1234-1234-123456abcdef",
    "page": 1,
    "per_page": 50,
    "total_pages": 1,
    "total_entries": 2,
    "plays": [
        {
            "song_id": 6834,
            "play_id": "G-Southeast-00259086cd54-1415213795446-616",
            "title": "While My Guitar Gently Weeps",
            "artist": "Beatles, The",
            "location": "Southeast",
            "business_date": "2014-11-05",
            "enqueue_time": "2014-11-05T18:56:35.446Z",
            "start_time": null,
            "end_time": null,
            "duration": 303077,
            "position": 0,
            "favorite": false
        },
        {
            "song_id": 67519,
            "play_id": "G-Southeast-00259086cd54-1414190084090-11078",
            "title": "Start It Up",
            "artist": "Banks, Lloyd ft. Kanye West, Swizz Beatz, Ryan Leslie & Fabolous",
            "location": "Southeast",
            "business_date": "2014-10-24",
            "enqueue_time": "2014-10-24T22:34:44.090Z",
            "start_time": "2014-10-24T22:37:54.058Z",
            "end_time": "2014-10-24T22:37:54.788Z",
            "duration": 302680,
            "position": 118,
            "favorite": true,
            "tags": [
                "Rap"
            ]
        }
    ]
}

Powered by Voicebox Industries