VL Group

Rhymba v3.6 Documentation

Getting a Stream

Getting a stream URL is as easy as calling a single method: GetStream. Let's walk you through the process.

  1. First, create your valid content API request token using the standard authentication process. Your method name is GetStream.
  2. Armed with that temporary request token, you'll issue a GET call to https://dispatch.mcnemanager.com/current/content.odata/GetStream with the following query string parameters. All fields are required to prevent end-user tampering. Be sure to enclose your string data in single quotes.
Field Name Type Description Example
access_hint string The access_hint value returned from the creation of the request token.
access_req string The access_req value returned from the creation of the request token.
access_token string The access_token value returned from the creation of the request token, not your regular access token..
mediaId int The media ID for which you're getting a stream. 123456
$format string Specify the format to return the data in. If this is missing or blank, 'atom' will be used. json
bitrate integer Specifies the kilobits per second for the returned content stream to be encoded in. 64, 128, 192, or 256
encoding string Name of the codec to use for the returned stream. 'mp3', 'flac', 'heaac' or 'aac'
fadeEnd integer Specifies the number of seconds for the track to fade out. This is from the end of the track after it has been trimmed by trimEnd. 0 for full length play. Only custom programs use other values.
fadeStart integer Specifies the number of seconds for the track to fade in. This is from the beginning of the track after it has been trimmed by trimStart. Typically 0
https boolean Specifies if the content should use secure URLs. This is only valid when protocol is set to 'http'. true or false
luid string Specifies the unique user id of the person that is listening to this stream. This value can be the same as suid if the same person generated and is listening to the stream. If a luid does not exist, pass in 'NA'. 'user123'
mono boolean Specifies if the audio should be encoded in monophonic format. true or false
protocol string Specifies the streaming protocol to return the content in. 'http' or 'hls'
suid string Specifies the unique user id of the person that generated this stream request. This value can be the same as luid if the same person generated and is listening to the stream. If a suid does not exist, pass in 'NA'. 'user123'
trimEnd integer Specifies the number of seconds to remove from the end of the track. This is useful for creating preview clips of a track. If this number is 0, it will not remove any content from the end of the track. Typically 0
trimStart integer Specifies the number of seconds to remove from the beginning of the track. This is useful for creating preview clips of a track. If this number is 0, it will not remove any content from the beginning of the track. Typically 0
  1. If the content is available to your system/application, this will return a Stream object with the following fields:
Field Name Type Description Example
id integer The unique id for media in the stream. 12345
url_segment_one string If the protocol requested was 'http' this will be the URL for the content stream. If 'hls' was requested, it will be the URL for the index file. "https://my.server.com/subdir/track1.mp3" or "https://hls.server.com/subdir/track1.m3u8"
url_segment_two string This will be blank.

That's all there is to it. You would then feed the HTTP stream URL to your player, and you should hear music.

Streaming a Playlist

You can also generate a stream from Media Ids stored in the Playlist Server using just the Playlist Id and the GetPlaylistStream method. Please note that only Media Ids matching Media in your Whitelist will play, and that labels change what Media is Whitelisted. Unknown ids will be skipped.

  1. First, create your valid content API request token using the standard authentication process. Your method name is GetPlaylistStream.
  2. Armed with that temporary request token, you'll issue a GET call to https://dispatch.mcnemanager.com/current/content.odata/GetPlaylistStream with the following query string parameters. All fields are required to prevent end-user tampering. Be sure to enclose your string data in single quotes.
Field Name Type Description Example
access_hint string The access_hint value returned from the creation of the request token.
access_req string The access_req value returned from the creation of the request token.
access_token string The access_token value returned from the creation of the request token, not your regular access token..
playlistId int The Playlist ID for which you're getting a stream. 123
$format string Specify the format to return the data in. If this is missing or blank, 'atom' will be used. json
bitrate integer Specifies the kilobits per second for the returned content stream to be encoded in. 64, 128, 192, or 256
encoding string Name of the codec to use for the returned stream. 'mp3', 'flac', 'heaac' or 'aac'
fadeEnd integer Specifies the number of seconds for the track to fade out. This is from the end of the track after it has been trimmed by trimEnd. 0 for full length play. Only custom programs use other values.
fadeStart integer Specifies the number of seconds for the track to fade in. This is from the beginning of the track after it has been trimmed by trimStart. Typically 0
https boolean Specifies if the content should use secure URLs. This is only valid when protocol is set to 'http'. true or false
luid string Specifies the unique user id of the person that is listening to this stream. This value can be the same as suid if the same person generated and is listening to the stream. If a luid does not exist, pass in 'NA'. 'user123'
mono boolean Specifies if the audio should be encoded in monophonic format. true or false
protocol string Specifies the streaming protocol to return the content in. 'http' or 'hls'
suid string Specifies the unique user id of the person that generated this stream request. This value can be the same as luid if the same person generated and is listening to the stream. If a suid does not exist, pass in 'NA'. 'user123'
trimEnd integer Specifies the number of seconds to remove from the end of the track. This is useful for creating preview clips of a track. If this number is 0, it will not remove any content from the end of the track. Typically 0
trimStart integer Specifies the number of seconds to remove from the beginning of the track. This is useful for creating preview clips of a track. If this number is 0, it will not remove any content from the beginning of the track. Typically 0
  1. If the content is available to your system/application, this will return a Stream object with the following fields:
Field Name Type Description Example
id integer The unique id for media in the stream. 12345
url_segment_one string If the protocol requested was 'http' this will be the URL for the content stream. If 'hls' was requested, it will be the URL for the index file. "https://my.server.com/subdir/track1.mp3" or "https://hls.server.com/subdir/track1.m3u8"
url_segment_two string This will be blank.

Notes About Encoding

If you request content in a format, bitrate, or with edits that we have not previously encoded, in the interest of speed, the "original" file will be streamed for http. In the meantime, an encoding request is fired off to our encoder complex with the parameters you specified. This allows for fast-start streaming even of content not previously encoded.

This does mean, however, that even if your service is a 128kbps MP4 streaming service, you may receive the original 256kbps or 320kbps MP3 file — which isn't ideal! To alleviate that scenario, some of our customers ask us to do pre-emptive encoding of a certain number of tracks expected to be popular based on usage across our platform and your specific customer demographic. Please consult with your VL Group account rep if you'd like to discuss options around this.