System for streaming
11627344 · 2023-04-11
Assignee
Inventors
Cpc classification
International classification
Abstract
The present invention relates to systems, methods, software applications and devices for the broadcasting of short-lived personal internet radio stations. Embodiments include software applications for live broadcasting over an internet network comprising a host mode and a recipient mode, wherein the software application may be executed on a connected mobile device to broadcast to many other recipients in a substantially synchronous manner. Embodiments provide for the live broadcasting of music and video content from a personal device to many listener or viewer devices, where content may be sourced from any number of locally stored or cloud-based content repositories.
Claims
1. A system for simulated live broadcasting a programmed audio music playlist session from a host device to multiple recipient devices over an internet network comprising: a software application for executing on the host device and the recipient devices, the software application capable of configuring only the host device to program, transmit and receive the programmed audio music playlist session and only the recipient devices to receive the audio music playlist session from a plurality of content stores containing content described by portions of the programmed audio music playlist session, respectively, and a streaming server for receiving the programmed audio music playlist session from the host device and streaming the music content described by the programmed audio music playlist session from the plurality of content stores to multiple recipient devices, wherein the programmed audio music playlist session is programmed at the host device using the software application and the programmed audio music playlist session is received at the multiple recipient devices using the software application wherein the streaming server is configured to: receive an authorization request from the software application executing on the host device, the authorization request specifying a redirect location, generate a user login prompt in response to the receipt of the authorization request, receive user login information from a user of the host device through the user login prompt, generate both an access token and an authorization code only in response to validating the received user login information, provide the authorization code to the redirect location, receive an access request from the software application executing on the host device, provide the access token to the software application executing on the host device only in response to the access request comprising the authorization code, and provide data associated with the streaming of the music content to the software application executing on the host device only in response to requests from the software application executing on the host device that comprise the access token.
2. The system according to claim 1 wherein the plurality of content stores are located on the host device or are accessible to the host device.
3. The system according to claim 2 wherein at least one of the plurality of content stores is located on a cloud server.
4. The system according to claim 1 comprising an upload server for receiving the music content described by portions of the programmed audio music playlist session from one or more content stores and transmitting the music content described by portions of the programmed audio music playlist session to the streaming server.
5. The system according to claim 1 comprising a management server for storing data arising from use of the software application.
6. A method of simulated live broadcasting a programmed audio music playlist session from a host device to multiple recipient devices over an internet network comprising: executing the software application on the host device in a host mode, the software application configured to, only on the host device, program, transmit and receive the programmed audio music playlist session, programming the programmed audio music playlist session from the host device by selecting a sequence of music content items stored at a plurality of content stores which are described by portions of the programmed audio music playlist session, respectively, and identifying internet locations of the music content items within the plurality of content stores, initiating the programmed audio music playlist session by initiating the transmission of the content items described by the programmed audio music playlist session from the plurality of content stores to a streaming server, streaming the music content items described by the programmed audio music playlist session from the streaming server to the recipient devices, executing the software application on one of the recipient devices in a recipient mode, the software application configured to, only on the recipient devices, receive the programmed audio music playlist session, identifying the programmed audio music playlist session from the recipient device, selecting the programmed audio music playlist session from the recipient device, receiving the substantially live relay of the content items described by the programmed audio music playlist session at a recipient device from the streaming server, receiving an authorization request from the software application executing on the host device, the authorization request specifying a redirect location, generating a user login prompt in response to the receipt of the authorization request, receiving user login information from a user of the host device through the user login prompt, generating both an access token and an authorization code only in response to validating the received user login information, providing the authorization code to the redirect location, receiving an access request from the software application executing on the host device, providing the access token to the software application executing on the host device only in response to the access request comprising the authorization code, and providing data associated with the streaming of the music content to the software application executing on the host device only in response to requests from the software application executing on the host device that comprise the access token.
7. The method according to claim 6 wherein the duration of the programmed audio music playlist session at the recipient devices lasts no longer than the duration of the programmed audio music playlist session at the host device.
8. The method according to claim 6 wherein an item of metadata describing the music content is transmitted whilst embedded in the programmed audio music playlist session.
9. The method according to claim 6 wherein data arising from use of the software application comprises metadata relating to the music content described by portions of the programmed audio music playlist session.
10. The method according to claim 6 wherein the music content items are located within cloud based content stores provided through content streaming services.
11. The method according to claim 6 wherein a content store is located on the host device.
12. The method according to claim 6 further comprising the step of: transmitting data arising from the use of the software application at the host device or at the recipient device to an application programming interface in communication with a management server.
13. The method according to claim 12 wherein the data arising from the use of the software application at the host device comprises metadata describing the music content item being transmitted, and wherein the metadata is transmitted periodically by the software application to the management server and is requested periodically by the recipient devices.
14. The method according to claim 6 wherein the programmed audio music playlist session is initiated by transmitting the music content items described by portions of the programmed audio session from a plurality of content stores to a streaming server via an upload server.
Description
BRIEF DESCRIPTION OF THE FIGURES
(1)
(2)
(3)
(4)
(5)
(6) Several embodiments of the invention are described in the following examples.
FUNCTIONAL OVERVIEW
(7) Embodiments according to the invention enable a host to broadcast a short lived Internet radio station, lasting no longer than the host's session, which can be received by one or many listeners.
(8) Several embodiments according to the invention are centred on the flow of two main data streams between hosts and listeners.
(9)
(10) The listener receives live music streams from the streaming servers in accordance with methods well known for live streaming to mobile devices. Typically, many listeners will connect with each host.
(11) The upload server receives uploaded data from hosts. It transcodes and filters digital audio for quality and efficiency, however no content is retained by the upload server. The streaming server consists of a typical streaming server well known to persons skilled in the art for receiving live audio streams and multiplexing them to many listeners. Again, audio content is not retained at the streaming server.
(12) Typical embodiment the invention comprises a native application for mobile devices developed for both iOS and Android, a cloud based streaming service to be progressively distributed globally to enhance performance in geographic concentrations of users, and an application programming interface and data store which is also cloud based and can authenticate users and keep analytic data. For convenience, the host and listener functions are both incorporated into the app and users can either be in a host or listener mode. However, embodiments may take the form of a single downloadable application for executing the downloading, installation and execution of a second application supplying additional functionality. For instance, a host application may execute the downloading, installation and execution of a second listener application.
(13) In listening mode, the app communicates with the data store via the API and displays lists of available sessions that a user can listen to. Once a session is selected, the listener is connected to the stream of content from the session being streamed by the streaming service. The listener can also view information about individual songs in the session being played on their devices display.
(14) In hosting mode, the app enables the user to build a playlist for a session from the songs on their device. When the session is commenced the device communicates with the API layer to transmit playlist and user information to the data store, and then streams the session to the streaming service which acts as a relay passing the stream directly to listener devices.
(15) The system comprises additional user functions. For instance, users can follow other users and in doing so become notified when the users they follow start a session. In addition, users listening to or hosting a session can also see a list of current users listening to the session and can also take part in a chat with the users listening to the session.
(16) System Components
(17) In the present embodiment, the iOS app is developed in Swift and Objective C using XCode8. It is specifically designed for iOS 7 and later. The Android app is developed in Java and C. It is specifically designed for Android 4.2 and later. The app has been developed using components that are freely licensable and modifiable and would be well known to persons skilled in the art.
(18) The streaming service comprises the Liquidsoap stream management and control servers and the Icecast streaming servers, running from local cloud services. Multiplexing the streamed content via Icecast streaming servers ensures that listener devices will play the audio feed substantially synchronously, to provide a ‘live’ experience to listeners. Once the ‘live’ broadcast has commenced, additional listeners can join in and listen to the multiplexed stream at substantially the same place in the session as all other listeners. This again simulates the live experience known to listeners of traditional broadcasting services.
(19) The API and data store comprises Apigee Edge and Apigee BAPS, respective€y, running from cloud services.
(20) All components of the system communicate under SSL encryption. In addition, user passwords are encrypted and hashed using strong encryption. All user interactions are logged and user emails are verified.
(21) User Features
(22) A user can select from public or private mode. In public mode a user makes available to all other users their username, sessions and social media interactions. In private mode the user only allows followers to view their username.
(23) A user can select from a public session on the discover screen in order to listen to the session and become a listener. The user can select from sessions of users being followed on the home screen in order to listen to the session and become a listener.
(24) A listener can view the list of songs in the selected session with the album art, title and artist of the current and previous songs shown along with the number of likes and dislikes each song has received from all listeners in the current session. The number of songs remaining and the duration of the session are also shown.
(25) A user can follow other users in order to see their private sessions on their home screen and to be notified whenever they start a session.
(26) Users can see the usernames of users that are following them, they can remove other users from their list of followers, they can see a list of the usernames of users they are following, they can unfollow a user they have previously followed, they can add and edit their profile information including username, email, gender, age, whether their sessions are public or private, they can select a picture from their local device to upload and use as their profile picture and they can change their password.
(27) A user can create a session in order to share their music and become a host. Music selected must comply with the licensing rules for the geography in which the user is located. They can also create a session by selecting quick start in order to start a session with ten random songs from their device. A user can create a session by selecting a playlist that is on their device in order to start a session of songs from that playlist in the order of that playlist. The music selected must comply with the licensing rules for the geography in which the user is located.
(28) A user can create a session by selecting songs from their device by artist or song title. Once a user adds sufficient songs to a session to meet the licensing requirements of their region, the session will start and the user will hear the session as will any listeners that have joined the session. Once the session has started the host can view the list of songs in the selected session with the album art, title and artist of all songs shown along with the number of likes and dislikes each song has received from all listeners in the current session.
(29) A host or listener can view and engage in the chat for the session and view the list of listeners to the session. The host can add songs to a running session using any of the methods used to add songs at an initial session creation. The host can also change the order of songs in the session provided the changes are within licensing rules.
(30) A user can sign in using the username and password provided at registration. These details are retained so the user can run the app without providing credentials again. A new user can register by providing a unique username, email address and password. A user can sign out from the profile screen, which will end any session the user is hosting and will close the connection to the server as the user is listening.
(31) A user can share the details of the app and the current song in the current session or host on social media or e-mail. A user can invite other users to follow them using the app, via social media or e-mail. A listener can like or dislike current songs or songs previously played in the current session, which is posted in the session chat. A listener can also stop listening to a session at any time.
(32) A listener can mark any song that is currently playing or has been played in the session for inclusion in their favourites list and it is added to the listener's favourites list. A user can remove any song from their favourites list at any time. A host can view their history of sessions by viewing a record of each of the sessions that they have hosted, in the form of a dashboard. The dashboard provides a visual or chart representation of four key items of data across the playlist and duration of the session. These items are the numbers of session members, song likes, song dislikes, and chat comments. A user can select a session from their history of sessions showing peak and average listeners against each song in the session. A listener can select a ‘buy’ function for a song in order to purchase it.
(33) User Journey
(34)
(35) Quick Start
(36) 10 unique random tracks are selected by the application from available songs on the device or an external content server or a third party streaming service that comply with all rules, then the playlist starts. This method cannot be used with other start methods. As soon as any song is selected under any other method, quick start is not selectable.
(37) Playlist
(38) Selecting this option shows a list of the playlists, in alphabetical order, on the device. The screen title should show ‘Playlists’. Users can select an entire playlist by clicking the checkbox next to a playlist. Alternatively, users can click on the name of a playlist and be presented with a view of the songs in the playlist (in playlist order) with check boxes. The screen title should show the name of the playlist. In the list of playlists, a playlist that has some of its songs selected should show a half-selected checkbox. If a playlist has all of its songs selected then its checkbox should be selected.
(39) All Songs
(40) Selecting this option shows a list of the songs, in alphabetical order by song title, on the device. The screen title should show ‘Songs’. Users can select a song by clicking the checkbox next to the song.
(41) Artist
(42) The artist option is the default, a list of artists appear below the menu which allows the choice between the first three methods. The screen title should show ‘Artists’. The list of artists is in alphabetical order. Users can select all songs from an artist by clicking the checkbox next to an artist. Alternatively, users can click on the name of an artist and be presented with a view of the songs by the artist, in alphabetical order by song title, with check boxes. The screen title should show the name of the artist. In the list of artists, an artist that has some of its songs selected should show a half-selected checkbox. If an artist has all of their songs selected then their checkbox should be selected.
(43) General
(44) Users can navigate between methods; selections are preserved and added to. Check boxes should always show clear, half selected or selected based upon the aggregate set of selections across all methods. Song order is based upon the sequence selected. Where a group of songs is selected via artists or playlist then the order will be the order shown in the underlying list. Where a song or group of songs is unselected then those songs should be removed from the order without changing the order of the songs remaining in the session. If these songs are re-selected, these songs will be added to the end of the playlist.
(45) A song has been ‘played’ when it has been broadcast in any part. If a song is stopped part way through (by a session being terminated or by the skip button being used by the host) then it is considered to have been played. If a song has been selected in a session and has then been skipped then it has also been played.
(46) Set of programming or curation rules govern part of the user's journey. Methods of ensuring the user's compliance with programming or curation rules is described in detail below.
(47) Enforcing Song Selection Rules
(48) The following rules are exemplary and apply to audiences in the United Kingdom only. Many other sets of rules are possible which may encompass parameters other than those shown below. Song selection rules (UK) are: Cannot webcast within three hours more than four songs by a particular artist. Cannot webcast within three hours more than three songs from a particular album. No particular song can be played within an hour of its previous playing. This rule is tested every time that a song or group of songs is selected. If the rule would be breached by a selection of a single song then a dialog appears and the selection of the checkbox is reversed. If the rule would be breached by a selection of a group of songs then a dialog appears explaining that some songs were not selected, and the maximum number of songs are selected (from top to bottom) and the balance are unselected.
(49) Enforcing Song Order Rules
(50) Song order rules are: No more than three songs by a particular artist can be played consecutively No more than two songs from a particular album can be played consecutively
(51) This rule is tested every time a change is made to a session. If the rule would be breached by a selection, deselection or re-ordering then the play order is reshuffled to comply with the rules by the smallest variation possible. A dialog then appears letting the user know an adjustment has been made.
(52) Enforcing Minimum Session Size Rule
(53) The minimum session size rule is: Must select at least 10 songs before commencing a session
(54) This rule is tested when users click the ‘Add to Playlist’ button. If the rule is breached then a dialog appears advising of the problem and users are able to add more songs using all methods. This rule is not relevant once a session has begun and should not be tested again.
(55) Completing Song Selection for a Session
(56) Song selection ends and the session starts playing if the user selects Quick. Start. Song selection ends and the session starts playing if the user selects the ‘Add to Playlist’ button and all rules are complied with.
(57) Buttons
(58) At the bottom of the screen there are three buttons. Select All: Selects all check boxes on the current screen. Clear All: Clears all check boxes on the current screen Add to Session: Start the session if rules are complied with.
(59) Search
(60) A single search function is universal and operates in Playlists, All Songs, Artists and List of Songs screens. Items on the screen are filtered to show only those that match the search term entered. The filtered list is updated with each change to the search term in real time. The search term is not case sensitive and must match the start of a word in the relevant field (artist, playlist or song title) to match. The search function will return the same results on every screen in the application.
(61) Exceptions to Licensing Rules
(62) If the Artist field of a song is blank or ‘Unknown’ or ‘Unknown Artist’ or ‘Various’ or ‘Various Artists’ then no rules are applied to that song. If the Album field of a song is blank or ‘Unknown’ or ‘Unknown Album’ but the artist field is not blank or ‘Unknown’ or ‘Unknown Artist’ then only the above rules for artist are applied. If the song name field is blank or ‘Unknown’ but the artist field is not blank or ‘Unknown’ or ‘Unknown Artist’ then only the above rules for artist are applied.
(63) Application Development
(64) Private API Endpoint Reference
(65) The components of the system communicate via well-defined APIs. The following details the APIs of the image server, upload (Liquidsoap) and streaming (Icecast) servers. In general apps will not call these APIs directly but will call only the Apigee API which will act as proxy for all of these.
(66) Image Server Summary
(67) A simple NodeJS web server running Express v4 is used with the following endpoints.
(68) TABLE-US-00001 Verb Endpoint Description GET /albumart Checks whether an image matching ‘artist’ and ‘album’ exists. GET /profile Checks whether a user profile image matching ‘userid’ exists. GET /bg Checks whether a user background image matching ‘userid’ exists. GET /session Checks whether a session cover image matching ‘sessionid’ exists. POST /upload/albumart Uploads an image using Content-Type of multipart/form- data. Writes to file system with convention: /img/<artist_1st_char>/<artist_2nd_char>/<artist>/<album>.png POST /upload/profile Uploads an image using Content-Type of multipart/form- data. Writes to file system with convention: /img/<userid_1st_char>/<userid_2nd_char>/<userid>.png POST /upload/bg <INCOMPLETE> POST /upload/session <INCOMPLETE>
(69) Request Parameters
(70) TABLE-US-00002 QUERY PARAMETER VALUE artist Required. The Artist name must be provided, preferably with special characters removed. album Required. The Album name must be provided, preferably with special characters removed. userid Required. The UserID must be provided. sessionid Required. The SessionID must be provided.
(71) TABLE-US-00003 GET /bg Checks whether a user's background image matching ‘userid’ exists. GET /session Checks whether a user's session cover image matching ‘sessionid’ exists.
(72) TABLE-US-00004 POST /upload/albumart Uploads an image using Content-Type of multipart/form- data. Writes to file system with convention: /img/albumart/<artist_1st_char>/<artist_2nd_char>/<artist>/<album>.png POST /upload/profile Uploads an image using Content-Type of multipart/form- data. Writes to file system with convention: /img/profile/<userid_1st_char>/<userid_2nd_char>/<userid>.png POST /upload/bg Uploads an image using Content-Type of multipart/form- data. Writes to file system with convention: /img/bg/<userid_1st_char>/<userid_2nd_char>/<userid>.png POST /upload/session Uploads an image using Content-Type of multipart/form- data. Writes to file system with convention: /img/session/<sessionid_1st_char>/< sessionid_2nd_char>/<sessionid>.png
(73) Custom Headers
(74) TABLE-US-00005 HEADER VALUE Content-Type Multipart/form-data
(75) Custom Form Data
(76) TABLE-US-00006 HEADER VALUE file Path to the file being uploaded
(77) Response Format
(78) On success, the HTTP status code in the response header is 201 OK and the response body contains a) SON object with the url path to the image. If the image already exists, a header status code 200 is returned. If no query parameter is provided, a header status code of 400 is given and the response body provides the error message.
(79) Public API Endpoint Reference
(80) The following provides detail of the API that apps can call. It acts as a proxy for the private APIs and for the data store which is the Apigee BAAS parse. A database entity diagram is provided at
(81) TABLE-US-00007 Verb Endpoint Description GET /v1/oauth2/authorize Once off authorization of access by an app on behalf of a user. Should be explicit part of registration. POST /v1/oauth2/token Used to request access and refresh tokens and also to get new access tokens when required GET /v1/sessions Show me all current public sessions. Match regex for user or session name in query parameters GET /v1/sessions/{userID} Show me the sessions being hosted by users {userID} follows GET /v1/sessions/host/{userID} Show me the details of a session being hosted by {userID} or error status GET /v1/sessions/members/{sessionID} Get all user data for the session members screen GET /v1/sessions/chat/{sessionID} Pass start and end time. Returns list of every comment between times POST /v1/sessions/chat/{sessionID} Add a comment to a chat and trigger push notifications GET /v1/sessions/votes/{sessionID} Return total votes for the session. For a time in the session, for a song in the session or by a user on a session depending upon query paramters PUT /v1/sessions/votes/{sessionID} Places a vote against a session at the current time by the current user or at specified time against a specified user based upon query parameters. POST /v1/sessions/listeners/{sessionID} Registers a user (UserID passed in query string) as a listener to a running session. DELETE /v1/sessions/listeners/{sessionID} Removes a registered listener (UserID passed in query string) from a running session. PUT /v1/sessions/{sessionID} Change the status of a session (normal hosts can only do this for sessions they are running) POST /v1/sessions Create a session. GET /v1/users/{userID} Get all user data for the public user profile screen. Includes followers and following lists. GET /v1/users All users or match regex in query parameters GET /v1/users/me Get all user data (public and private) for the current user POST /v1/users Create a new user record PUT /v1/users/{userID} Add/remove follower. Add/remove following. Update any profile data. Also used for updating installations. Specific combinations of query parameters do lightweight viewing or returning of following/followers with referential integraity GET /v1/playlists/{sessionID} Get all playlist metadata or only what allowed to see if not host. PUT /v1/playlists/{sessionID} Update a playlist as host GET /v1/favourites/{userID} Retrieve list of metadata for all favourited items for userID with index numbers POST /v1/favourites/{userID} Create a new favourite with supplied metadata DELETE /v1/favourites/{userID} Delete a favourite with supplied index number POST /v1/streams/{sessionID} parameters are start | skip |update | end. ‘start’ returns a sessionsimple object with the mountpoint completed in the body. ‘start’ also triggers a push notification to the users who follow the host. GET /v1/streams/{sessionID} Return full icecast data in JSON on the stream GET /v1/albumart Parameters are artist and album. If the art is not in the cache then returns a status and the app must post new art. POST /v1/albumart Parameters are artist and album
(82) About the API
(83) Through the BlueJay Music API the application can retrieve and manage BlueJay Music content. The base address of the API is https://api.bluejaymusic.com. There are several endpoints at that address, each with its own unique path. Many endpoints are open and special permissions is not needed to access them. To access private data through the Web API, such as user profiles and playlists, an application must get the user's permission to access the data.
(84) Requests
(85) The Bluejay Music API is based on REST principles: data resources are accessed via standard HTTPS requests in UTF-8 format to an API endpoint. Where possible, the API strives to use appropriate HTTP verbs for each action:
(86) TABLE-US-00008 VERB DESCRIPTION GET Used for retrieving resources. POST Used for creating resources. PUT Used for changing/replacing resources or collections. DELETE Used for deleting resources.
(87) BlueJay Music URIs and IDs
(88) In requests to the Web API and responses from it, the following parameters will frequently be encountered:
(89) TABLE-US-00009 PARAMETER DESCRIPTION EXAMPLE Bluejay URI The resource identifier that you can bluejay:track:6rqhFgbbKwnb9MLmUQDhG6 enter, for example, in the BlueJay web client's search box to locate an artist, album, or track. To find a BlueJay Music URI simply right-click (on Windows) or Ctrl-Click (on a Mac) on the artist's or album's or track's name BlueJayID The base-62 identifier that you can find 6rqhFgbbKwnb9MLmUQDhG6 at the end of the BlueJay URI (see above) for an artist, track, album, playlist, etc. Unlike a BlueJay URI, a BlueJay ID does not clearly identify the type of resource; that information is provided elsewhere in the call BlueJay Music The unique string identifying the BlueJay wizzler user ID user that you can find at the end of the BlueJay URI for the user. The ID of the current user can be obtained via the Web API endpoint https://api.bluejaymusic.com/v1/users/me. BlueJay URL An HTML link that opens a track, album, http://open.bluejaymusic.com/track/6rqhFgbbkwnb9MLmUQDhG6 app, playlist or other BlueJay Music resource in a BlueJay Music App.
(90) Rate Limiting
(91) To make the API fast for all users, rate limits apply. Unauthenticated requests are processed at the lowest rate limit. Authenticated requests with a valid access token benefit from higher rate limits even if the endpoint does not require an access token to be passed in the call. Rate limiting is applied on an application basis (based on client id), regardless of the number of users using it.
(92) The number of requests is reduced by using endpoints that fetch multiple entities. Therefore, when making many requests to get single tracks, albums or artists, endpoints such as Get Several Tracks, Get Several Albums or Get Several Artists may be used.
(93) Responses
(94) All data is received as a JSON object.
(95) Timestamps
(96) Timestamps are returned in ISO 8601 format as Coordinated Universal Time (UTC) with zero offset: YYYY-MM-DDTHH:MM:SSZ. If the time is imprecise (for example, the date/time of an album release), an additional field will show the precision; see for example, release_date in an album object.
(97) Pagination
(98) Some endpoints support a paging of the dataset, taking an offset and applying a limit. Offset numbering is zero-based and omitting the offset parameter will return the first X elements. Requests that return an array of items are automatically paginated if the number of items vary (for example, tracks in a playlist). In this case, the results are returned within a paging object.
(99) Conditional Requests
(100) Most API responses come with appropriate cache-control headers set to assist in client-side caching. If a cached response arises, the response is not requested again until the response has expired; if the response contains an ETag, the If-None-Match request header is matched to the ETag value.
(101) Response Status Codes
(102) The API uses the following response status codes, as defined in the RFC 2616 and RFC 6585:
(103) TABLE-US-00010 STATUS CODE DESCRIPTION 200 OK - The request has succeeded. The client can read the result of the request in the body and the headers of the response. 201 Created - The request has been fulfilled and resulted in a new resource being created. 202 Accepted - The request has been accepted for processing, but the processing has not been completed. 204 No Content - The request has succeeded but returns no message body. 304 Not Modified. See Conditional requests. 400 Bad Request - The request could not be understood by the server due to malformed syntax. The message body will contain more information; see Error Details. 401 Unauthorized - The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials. 403 Forbidden - The server understood the request, but is refusing to fulfill it. 404 Not Found - The requested resource could not be found. This error can be due to a temporary or permanent condition. 429 Too Many Requests - Rate limiting has been applied. 500 Internal Server Error. You should never receive this error. Please report it to us. 502 Bad Gateway - The server was acting as a gateway or proxy and received an invalid response from the upstream server. 503 Service Unavailable - The server is currently unable to handle the request due to a temporary condition which will be alleviated after some delay. You can choose to resend the request again.
(104) Error Details
(105) The API uses two different formats to describe an error.
(106) Authentication Error Object
(107) When the application makes requests to the API which are related to authentication or authorization, e.g. retrieving an access token or refreshing an access token, the error response follows RFC 6749 on The QAuth 2.0 Authorization Framework.
(108) TABLE-US-00011 VALUE KEY TYPE VALUE DESCRIPTION error string A high level description of the error as specified in RFC 6749 Section 5.2. error_description string A more detailed description of the error as specified in RFC 6749 Section 4.1.2.1.
(109) Regular Error Object
(110) Apart from the response code, unsuccessful responses return information about the error as an error BON object containing the following information:
(111) TABLE-US-00012 VALUE KEY TYPE VALUE DESCRIPTION status integer The HTTP status code (also returned in the response header; see Response Status Codes for more information). message string A short description of the cause of the error.
(112) Authentication
(113) Some requests to the Web API require authentication. This is achieved by sending a valid ° Ruth access token in the request header. To access a user's personal information, an access token is needed, generated by requesting the user's permission to access the data.
(114) Sign-Up Flow
(115) When the user opens the app for the first time, they are presented with the login/signup screen. The user selects signup and provides the details required. The user then confirms that all details are accurate.
(116) Log-In Flow
(117) When the user opens the app after having logged off, or has re-downloaded the app on a new phone, or is accessing the app on a friend's phone (and other such scenarios where they already have an account), they will enter their username and password they supplied during signup.
(118) This will return an access token that allows access to the main API. The access token is extracted from the response and stored on the app. The token may be set to not expire at all so it can be saved for the long term, however, a refresh token may alternatively be supplied that can be sent to refresh the provided access token.
(119) Authorization Code Flow
(120) The following method is suitable for long-running applications which the user logs into once. It provides an access token that can be refreshed. Since the token exchange involves sending a secret key, this occurs in a secure location, like a backend service, not from a client like a browser or mobile app. This flow is described in RFC-6749.
(121) User Authorization Requests
(122) With reference to
(123) TABLE-US-00013 QUERY PARAMETER VALUE client_id Required. The client ID provided to you by BlueJay Music when you register your application. response_type Required. Set it to code. redirect_uri Required. The URI to redirect to after the user grants/denies permission. This URI needs to have been entered in the Redirect URI whitelist that you specified when you registered your application. The value of redirect_uri here must exactly match one of the values you entered when you registered your application, including upper/lowercase, terminating slashes, etc. state Optional, but strongly recommended. The state can be useful for correlating requests and responses. Because your redirect_uri can be guessed, using a state value can increase your assurance that an incoming connection is the result of an authentication request. If you generate a random string or encode the hash of some client state (e.g., a cookie) in this state variable, you can validate the response to additionally ensure that the request and response originated in the same browser. This provides protection against attacks such as cross-site request forgery. scope Optional. A space-separated list of scopes:. If no scopes are specified, authorization will be granted only to access publicly available information: that is, only information normally visible in the Bluejay Music apps. show_dialog Optional. Whether or not to force the user to approve the app again if they've already done so. If-False (default), a user who has already approved the application may be automatically redirected to the URI specified by redirect_uri. If true, the user will not be automatically redirected and will have to approve the app again.
(124) Authorization of Access Within the Scopes
(125) The BlueJay Music API service presents details of the scopes for which access is being sought. If the user is not logged in, they are prompted to do so using their BlueJay Music credentials. When the user is logged in, they are asked to authorize access to the data sets defined in the scopes.
(126) Redirected Back to the Specified URI
(127) After the user accepts (or denies) the request, the BlueJay Music API service redirects back to the redirect_uri(3).
(128) If the user has accepted the request, the response query string will contain the following parameters:
(129) TABLE-US-00014 QUERY PARAMETER VALUE code An authorization code that can be exchanged for an access token. state The value of the state parameter supplied in the request.
(130) If the user has not accepted the request or an error has occurred, the response query string will contain the following parameters:
(131) TABLE-US-00015 QUERY PARAMETER VALUE error The reason authorization failed, for example: “access_denied” state The value of the state parameter supplied in the request.
(132) Requests for Refreshed and Access Tokens
(133) When the authorization code has been received, it is exchanged with an access token by making a POST request to the BlueJay Music API service to its /v1/oauth2/token endpoint. The body of this POST request must contain the following parameters:
(134) TABLE-US-00016 REQUEST BODY PARAMETER VALUE grant_type Required. As defined in the OAuth 2.0 specification, this field must contain the value “authorization_code”. code Required. The authorization code returned from the initial request to the Account's/v1/oauth2/authorize endpoint. redirect_uri Required. This parameter is used for validation only (there is no actual redirection). The value of this parameter must exactly match the value of redirect_uri supplied when requesting the authorization code.
(135) TABLE-US-00017 HEADER PARAMETER VALUE Authorization Required. Base 64 encoded string that contains the client ID and client secret key. The field must have the format: Authorization: Basic <base64 encoded client_id:client_secret>
(136) On success, the response from the BlueJay Music API service has the status code 200 OK in the response header, and the following JSON data in the response body:
(137) TABLE-US-00018 VALUE KEY TYPE VALUE DESCRIPTION access_token string An access token that can be provided in subsequent calls, for example to BlueJay Music API services. token_type string How the access token may be used: always “Bearer”. scope string A space-separated list of scopes which have been granted for this access_token expires_in int The time period (in seconds) for which the access token is valid. refresh_token string A token that can be sent to the BlueJay Music API service in place of an authorization code. (When the access code expires, send a POST request to the API service/v1/oauth2/token endpoint, but use this code in place of an authorization code. A new access token will be returned. A new refresh token might be returned too.)
(138) Requesting an Access Token from the Refresh Token
(139) Access tokens are deliberately set to expire after a short time, after which new tokens may be granted by supplying the refresh token originally obtained during the authorization code exchange.
(140) The request is sent to the /v1/oauth2/token endpoint of the Bluejay Music API service. The body of this POST request must contain the following parameters:
(141) TABLE-US-00019 REQUEST BODY PARAMETER VALUE grant_type Required. Set it to “refresh_token”. refresh_token Required. The refresh token returned from the authorization code exchange.
(142) The header of this POST request must contain the following parameter:
(143) TABLE-US-00020 HEADER PARAMETER VALUE Authorization Required. Base 64 encoded string that contains the client ID and client secret key. The field most have the format: Authorization: Basic <base64 encoded client_id:client_secret>
(144) Sessions
(145) Sessions are the data structure through which most interaction with BlueJay Music takes place. A session contains an instance of a playlist along with a chat and it is created by a host. It exists for a period of time after which it becomes dormant and invisible to all users except the host and administrators who can use the data it contains for analytics.
(146) TABLE-US-00021 GET /v1/sessions Show me all current public sessions. Match regex for user or session name in query parameters QUERY PARAMETER VALUE Limit Optional. The maximum number of sessions to return. Default: 20. Minimum: 1. Maximum: 50. Offset Optional. The index of the first session to return. Default: 0 (the first object). Use with limit to get the next set of sessions. q Required. The search query's keywords (and optional field filters and operators), for example q = roadhouse %2Oblues.
(147) Request Parameters Encoding Spaces Encode spaces with the hex code %20 or +. Keyword Matching Matching of search keywords is not case-sensitive. (Operators, however, should be specified in uppercase.) Keywords will be matched in any order unless surrounded by double quotation nnarks:q=roadhouse&20blues will match both “Blues Roadhouse” and “Roadhouse of the Blues” whileq=“roadhouse&20blues” will match “My Roadhouse Blues” but not “Roadhouse of the Blues”.
(148) Searching for playlists will return results where the query keyword(s) match any part of the playlist's name or description. Only popular public playlists are returned. Operators The operator NOT can be used to exclude results. For example q=roadhouse/G20NOT%2Obluesreturns items that match “roadhouse” but excludes those that also contain the keyword “blues”. Similarly, the OR operator can be used to broaden the search: q=roadhouseT0200R%20blues returns all results that include either of the terms. Only one OR operator can be used in a query.
(149) Note that operators must be specified in uppercase otherwise they will be treated as normal keywords to be matched. Wildcards The asterisk (*) character can, with some limitations, be used as a wildcard (maximum: 2 per query). It will match a variable number of non-white-space characters. It cannot be used in a quoted phrase, in a field filter, when there is a dash (“-”) in the query, or as the first character of the keyword string.
(150) Response Format
(151) On success, the HTTP status code in the response header is 200 OK and the response body contains session complete objects wrapped in a paging object. On error, the header status code is an error code and the response body contains an error object.
(152) Sample Request
(153) TABLE-US-00022 GET /v1/sessions/{userID} Show me the sessions being hosted by users {userID} follows
(154) This API returns an array of session complete objects for private sessions that are being currently hosted by the users that the specified user follows.
(155) TABLE-US-00023 GET /v1/sessions/host/{userID} Show me the details of a session being hosted by {userID} or error status
(156) This API returns a single session complete object if the specified user is hosting a session.
(157) TABLE-US-00024 GET /v1/sessions/members/{sessionID} Get all user data for the session members screen
(158) This API returns an array of uuid, username and profile picture URI
(159) TABLE-US-00025 GET /v1/sessions/chat/{sessionID} Pass start and ed time. Returns list of every comment between times
(160) This API returns an array of ChatComment objects.
(161) TABLE-US-00026 POST /v1/sessions/chat/{sessionID} Add a comment to a chat and trigger push notifications
(162) This API posts a ChatComment object.
(163) TABLE-US-00027 GET /v1/sessions/votes/{sessionID} Return total votes for the session. For a time in the session, for a song in the session or by a user on a session depending upon query paramters
(164) Query parameters are a) time range OR b) song index AND c) UserID
(165) TABLE-US-00028 PUT /v1/sessions/votes/{sessionID} Places a vote against a session at the current time by the current user or at specified time against a specified user based upon query parameters.
(166) TABLE-US-00029 POST /v1/sessions/listeners/{sessionID} Registers a user (UserID passed in query string) as a listener to a running session
(167) Returns mount point if valid. If session not running returns error status.
(168) TABLE-US-00030 DELETE /v1/sessions/listeners/{sessionID} Removes a registered listener (UserID passed in query string) from a running session
(169) Returns success status if user removed. Error status for use not in session, session not running.
(170) TABLE-US-00031 PUT /v1/sessions/{sessionID} Change the status of a session (normal hosts can only do this for sessions they are running)
(171) Status can be New, Playing or Ended. Changing the Status to ‘Ended’ should stop the stream if it is is still running.
(172) TABLE-US-00032 POST /v1/sessions/ Create a session
(173) Create a session and provide fields:
(174) All other fields will be controlled by the system or added with the playlists API.
(175) Users
(176) Everyone who uses the BlueJay app will be present in the user's collection. This endpoint provides the means to create, change and read information from this collection.
(177) TABLE-US-00033 GET /v1/users/{userID} Get all user data for the public user profile screen. Includes followers and following lists.
(178) Returns a single Usercomplete or an array.
(179) TABLE-US-00034 GET /v1/users All users or match regex in query parameters
(180) TABLE-US-00035 POST /v1/users Create a new user record
(181) Create a user with fields
(182) TABLE-US-00036 PUT /v1/users/{userID} Add/remove follower. Add/remove following. Update any profile data. Also used for updating installations.
(183) Query string should indicate the change to be made.
(184) Playlists
(185) Playlists are part of the Sessions object. This endpoint allows specific manipulation of playlists.
(186) TABLE-US-00037 GET /v1/playlists/{sessionID} Get all playlist metadata or only what allowed to see if not host.
(187) Returns a session complete object. If a listener then all songs that have not been played should have all metadata removed but the starte dat, end sat, total songs, playing song and duration should all be correct for the entire session.
(188) TABLE-US-00038 PUT /v1/playlists/{sessionID} Update a playlist as host
(189) Takes a session complete object but only the songs array is read into the database. Changes take effect from the next song. Songs in the past and the current song should not be changed or there may be unpredictable results.
(190) Favourites
(191) Favourites are metadata objects for songs that a user has flagged as favourite. In time users will be able to purchase songs and other interactions based upon their favourites.
(192) TABLE-US-00039 GET /v1/favourites/{userID} Retrieve list of metadata for all favourited items for userID with index numbers
(193) Returns an array of favourites objects in a paging object.
(194) TABLE-US-00040 POST /v1/favourites/{userID} Create a favourite with supplied metadata
(195) Posts a favourites object.
(196) TABLE-US-00041 DELETE /v1/favourites/{userID} Delete a favourite with supplied index number
(197) Can also provide the original rnetadata or an index to the array returned by GET.
(198) Streams
(199) Initiates the playing of a playlist. A valid session is built with POST /v1/sessions and it contains a valid playlist built with PUT /v1/playlists/{sessionID}.
(200) TABLE-US-00042 POST /v1/streams/{sessionID} parameters are start | skip |update |end
(201) Update time fields of session ID and return the mount point for ‘start’.
(202) TABLE-US-00043 GET /v1/streams/{sessionID} Return full icecast data in JSON on the stream
(203) Albumart
(204) One standard sized image is kept for each unique artist+album. The same API is used to get images for users by specifying artist=profile or background and album=username. Profile pictures have dimensions of (256×256). Background pictures have dimensions of (x*y)
(205) TABLE-US-00044 GET /v1/streams/albumart Parameters are artist and album
(206) Parameters are passed in the query string. Path to album art is returned or an error status if not found.
(207) TABLE-US-00045 GET /v1/streams/albumart Parameters are artist and album
(208) Post PNG 256×255 image. Parameters are passed in the query string. New image overwrites any previous one. Status should indicate success (new), success (overwrite) or fail.
(209) Throughout this specification the word “comprise”, or variations such as “comprises” or “comprising”, will be understood to imply the inclusion of a stated element, integer or step, or group of elements, integers or steps, but not the exclusion of any other element, integer or step, or group of elements, integers or steps.
(210) All publications mentioned in this specification are herein incorporated by reference. Any discussion of documents, acts, materials, devices, articles or the like which has been included in the present specification is solely for the purpose of providing a context for the present invention. It is not to be taken as an admission that any or all of these matters form part of the prior art base or were common general knowledge in the field relevant to the present invention as it existed in Australia or elsewhere before the priority date of each claim of this application.
(211) While the invention has been described above in terms of specific embodiments, it is to be understood that the invention is not limited to these disclosed embodiments. Upon reading the teachings of this disclosure many modifications and other embodiments of the invention will come to the mind of those skilled in the art to which this invention pertains, and which are intended to be and are covered by both this disclosure and the appended claims.
(212) It is indeed intended that the scope of the invention should be determined by proper interpretation and construction of the appended claims and their legal equivalents, as understood by those skilled in the art relying upon the disclosure in this specification and the attached drawings.