VL Group

Rhymba v3.6 Documentation

The Rhymba Media Player (Beta)

The Rhymba Media Player is a ready-to-use, prebuilt JavaScript library that allows you to quickly add playback of Rhymba Streaming API-powered streams to your web application, designed to get audio from the Rhymba Content API and into your user's ears as directly as possible. We're continuously evolving its features & functionality, and have begun using it for all of our own projects, so it's constantly receiving QA, fixes, and updates. We're calling it "beta" for the time being even though it's being used in production, because we do have additional features we'd like to add, as well as test. You can of course "roll your own" solution, but for our customers looking to get up and running quickly with a minimum of development, the Rhymba Media Player is our recommended way to roll.

Let's take a look at getting a stream up and running quickly.

Playing a Stream - QuickStart

Playing music from the Rhymba Content API in your browser is as simple as knowing the Media ID of the track you want to play.

  1. First get yourself a current version of jQuery, because it's great, and also because the Rhymba javascript libraries need it to work.
  2. Second, add the Rhymba Media Player script at this link to your page. We recommend adding it immediately before the end of your <body> tag so that it won't get in the way of your page's content.
  3. Next, create a valid Content API token set using the process described in “Getting a Stream”.
  4. Equipped with your Content API token, you can now create a Rhymba Media Player instance to play your stream with. In a new <script> tag, call the rhymba.media.Player() method, passing it your content API tokens in a configuration object like so:
    var myPlayer = rhymba.media.Player({
        tokens: {
            access_token: "[YourContentApiToken].access_token",
            access_hint: "[YourContentApiToken].access_hint",
            access_req: "[YourContentApiToken].access_req"
        }
    });
    
  5. Playing music is now as simple as calling the player's .play() method with the ID of the track you want to play. For instance:
    myPlayer.play("[MediaID]");
  6. But unless you only used the default parameters when you created your Content API Token, you'll probably want to do the sophisticated thing, and tell the Player exactly how you want to play that track:
    var myTrack = {
        $format: "[String]",
        mediaId: [Integer],
        bitrate: [Integer],
        protocol: "[String]",
        encoding: "[String]",
        suid: "[String]",
        luid: "[String]",
        mono: [Boolean],
        https: [Boolean],
        trimStart: [Integer],
        trimEnd: [Integer],
        fadeStart: [Integer],
        fadeEnd: [Integer]
    };
    myPlayer.play(myTrack);

Special Case: Preview Streams

For previews, things work only a little differently. Instead of needing to use a full Content API Token Set, you can get away with just your regular Rhymba Access Token (although a full set won't hurt matters). Then, when you want to preview your tracks, just make sure you add ".preview" to their media IDs.

For example:

var myPlayer = rhymba.media.Player({
    tokens: "[YourRhymbaAccessToken]"
});
myPlayer.play("[MediaID].preview");

More About the Rhymba Media Player

The Rhymba Media Player is a simple but flexible beast. The only required constructor option is your Content API Token Set. However, there are some additional options that can make getting your specific functionality simpler.

Options

Field Name Type Description Example
tokens object A javascript object with string properties for the three parts of a Rhymba Content API token.
tokens: {
	access_token: "",
	access_hint: "",
	access_req: ""
}
content object The Rhymba Media Player will use the properties of this object in the corresponding fields of a request to the Rhymba Content API when resolving the content stream url of any media assigned to it without one. While not required, we strongly suggest that you use values corresponding to the fields you used when requesting your Content API token.
content: {
	$format:  json,
	bitrate:  256,
	encoding:  'mp3',
	fadeEnd:  0,
	fadeStart:  0,
	https:  false,
	luid:  'NA',
	mono:  false, 
	protocol:  'rtmp',
	suid:  'NA',
	trimEnd:  0,
	trimStart:  0
}	
volume decimal The volume at which to play audio, with 0 being silent and 1 being maximum. 0.5
bufferTime integer The duration, in seconds, of playback time to load before an item begins to play. During playback, the player will always attempt to this many seconds of audio data in memory. See: the .bufferTime() method. 3
autoResolve boolean If true, the Rhymba Media Player instance will immediately attempt to use the Rhymba Content API to determine a content stream url for any media assigned to it without one. TODO: content object true
autoLoad boolean If true, the Rhymba Media Player instance will immediately begin loading audio data for any media assigned to it, even before being told to play. false
any Event Handler function(event) Any of the Rhymba Media Player's Event Handlers can be included as a construction option.
onPlayable: function(event){
	console.log(event)
}

Example: Advanced Construction

var myPlayer = rhymba.media.Player({
    tokens: {
        access_token: "[YourContentApiToken].access_token",
        access_hint: "[YourContentApiToken].access_hint",
        access_req: "[YourContentApiToken].access_req"
    },
    content: {
        $format: "json",
        bitrate: 256,
        protocol: "rtmp",
        encoding: "mp3",
        suid: "[YourStreamId]",
        luid: "[YourListenderId]",
        mono: false,
        https: false,
        trimStart: 0,
        trimEnd: 0,
        fadeStart: 0,
        fadeEnd: 0
    },
    autoResolve: true,
    autoLoad: true,
    bufferTime: 10,
    volume: .75,
    onReady: function(event){
        myPlayer.play("[MediaId]");
    },
    onPlay: function(event){
        window.console.log("playing");
    },
    onPause: function(event){
        window.console.log("playing");
    },
    onResume: function(event){
        window.console.log("playing");
    },
    onComplete: function(event){
        window.console.log("complete");
    },
    onStop: function(event){
        window.console.log("stopped");
    }
});

Playback Methods

Name Arguments Description Returns Example
play Media If invoked with an argument, assigns that media to the Rhymba Media Player instance. The current media is then loaded and played.
pause Pauses playback if the Player is currently playing.
resume Resumes playback if the Player is currently paused.
togglePause Pauses playback if the player is playing, resumes playback if the Player is paused, and plays the current media in any other state.
stop Stops playback. Stopped media will continue to load if 'autoLoad' is true.
toggleStop Plays the current media if playback is stopped, stops playback in any other state.

Configuration Methods

Name Arguments Description Returns Example
media Media Gets/Sets the media item currently assigned to the Rhymba Media Player instance. Media
load Media If invoked with an argument, assigns that media to the Rhymba Media Player instance. The currently assigned media is then loaded for playback.
volume decimal Gets/Sets the volume at which to play audio media. decimal
position integer Gets/Sets the current playback position of the current media. If assigned a value greater than the duration of the media stream, playback will end as if the stream had played to completion. integer
bufferTime integer Gets/Sets the time, in seconds, that media streams must have loaded in order to be considered playable. See: bufferTime option integer
bufferLength integer Gets the time, in seconds, of playback content currently buffered for the assigned media integer
autoResolve boolean Gets/Sets the autoResolve option. If autoResolve is true, then any media assigned to the Player without a content url will have one resolved for it using the Rhymba Content API, as configured in the content option. boolean
preResolve Media If invoked with an argument, attempts to resolve a content url for that Media Object using the Rhymba Content API, as configured in the content option. If invoked without an argument, attempts to resolve a content url for the media currently assigned to the Player.
autoLoad boolean Gets/Sets the autoLoad option. If autoLoad is true, then any media assigned to the Player will immediately have a content url resolved for it using preResolve method. If a content url is resolved, playback data will be loaded from that url immediately. boolean
preLoad Media If invoked with an argument, attempts to resolve a content url for that Media Object. If a content url is resolved, playback data will be loaded from that url in the background.

Status Methods

Name Arguments Description Returns Example
isReady Returns true if the Player Instance has finished initializing and is ready to begin playing media. boolean
isPlayable Returns true if the currently assigned media has a content stream url and is able to begin playing. boolean
isPlaying Returns true if the player is currently playing. boolean
isPaused Returns true if the player is currently paused. boolean
isStopped Returns true of the player is current stopped. boolean
isComplete Returns true if the current media has been played to completion. boolean

Event Handlers

The Rhymba Media Player emits a variety of events reflecting changes in the state of the Player or the media being played. Callback functions for these events are assigned using the convenience methods listed here. You can assign as many callback functions to a given event as you need, and release them later using the .removeEventListener() method: all of the methods below return a numeric string identifying the particular callback-function + event-type pairing created, so when you don't need that callback any longer, you can use the token with .removeEventListener() to get rid of it.

Callback functions will be invoked with an event argument containing details about the related search. These details are stored in the event's .data property.

Name Arguments Description Returns Example
onReady function( event ) Invoked once the Rhymba Media Player instance has initialized and is ready to begin playing media. string
myPlayer.onReady(function(event){
	console.log(event.type, event.data);
});
onPlay function( event ) Invoked whenever the Player begins to play. string
myPlayer.onPlay(function(event){
	console.log(event.type, event.data);
});
onPause function( event ) Invoked whenever the Player is paused. string
myPlayer.onPause(function(event){
	console.log(event.type, event.data);
});
onResume function( event ) Invoked whenever the Player resumes playing from a paused state. string
myPlayer.onResume(function(event){
	console.log(event.type, event.data);
});
onComplete function( event ) Invoked when the Player has played its current media to completion. string
myPlayer.onComplete(function(event){
	console.log(event.type, event.data);
});
onStop function( event ) Invoked when the Player stops playback. string
myPlayer.onStop(function(event){
	console.log(event.type, event.data);
});
onMediaChange function( event ) Invoked whenever the Player's current media changes, for example by calling .play("[mediaId]") or .load("[mediaId]"). string
myPlayer.onReady(function(event){
	console.log(event.type, event.data);
});
onPlayable function( event ) Invoked when the Player's current media becomes playable. string
myPlayer.onPlayable(function(event){
	console.log(event.type, event.data);
});
onPlaybackStatus function( event ) Invoked whenever the Player's current playback status changes. You can check out the various status values by calling rhymba.media.Player.statuses(). string
myPlayer.onPlaybackStatus(function(event){
	console.log(event.type, event.data);
});
onPlaybackPosition function( event ) Invoked whenever the Player's current playback position changes. string
myPlayer.onPlaybackPosition(function(event){
	console.log(event.type, event.data);
});
onPlaybackFailure function( event ) Invoked whenever playback fails for the current media. string
myPlayer.onPlaybackFailure(function(event){
	console.log(event.type, event.data);
});
whilePlaying function( event ) Invoked continuously while the Player is playing. string
myPlayer.whilePlaying(function(event){
	console.log(event.type, event.data);
});
whileLoading function( event ) Invoked continously while playback data is loading. string
myPlayer.whileLoading(function(event){
	console.log(event.type, event.data);
});
addEventListener string, function( event ) Add a new callback function for the named event, used internally by all of the convenience methods above. Check out available events using rhymba.media.Player.events() string
myPlayer.addEventListener(
	'change.ready', 
	myCallbackFunction
);
removeEventListener string Cancels an existing event handler callback based on its token. myPlayer.removeEventListener("23")

Media Objects

Media Objects are any objects assigned to the Media Player to represent an item of Rhymba Content. The simplest form of Media Object is a string indicating the Rhymba Content item's ID, but any object with a 'mediaId' property will do. This is convenient if you already happen to have a lot of Rhymba Content as JSON objects, or if you want to play back a given track a little differently from others.

For example, all of the objects below are valid as javascript Media Objects:

//* A media ID as a string
var exampleMediaA = "555555.preview";
//* An object literal
var exampleMediaB = {
    mediaId: "555555",
    bufferTime: 10,
    volume: .75
};
//* An object literal for a track whose content url(s) you already know: 
var exampleMediaC = {
    mediaId: "555555",
    url: "mp3:/some/media",
    serverUrl: "rtmp://some.streaming.server/"
};
//* A deserialized JSON object from the Search API
var exampleMediaD = {
    length: 209,
    id: 555555,
    artist_id: 0,
    album_id: 0,
    dateadded: "/Date(1326042484203)/",
    format_id: 9,
    isexplicit: false,
    tracknumber: 1,
    volumenumber: 1,
    streetdate: "/Date(1308614400000)/",
    releasedate: "/Date(1308614400000)/",
    artist_dateupdated: "/Date(1374274742707)/",
    artist_dateadded: "/Date(1301920882867)/",
    album_artistid: 0,
    album_isexplicit: false,
    album_status_id: 7,
    album_volumenumber: 1,
    album_numberoftracks: 13,
    album_streetdate: "/Date(1308614400000)/",
    album_releasedate: "/Date(1308614400000)/",
    title: "Example Track Title",
    artist_name: "Example Artist",
    album_name: "Example Album Name",
    album_artist_name: "Example Artist",
    album_label_name: "Example Label"
};