Getting a Stream
Getting a stream URL (or, in the case of Flash/RTMP, the application & stream endpoint) is as easy as calling a single method: GetStream. Let's walk you through the process.
- First, create your valid content API request token using the standard authentication process. Your method name is GetStream.
- 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.
|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', 'rtmp' 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|
- If the content is available to your system/application, this will return a Stream object with the following fields:
|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 'rtmp' was requested, it will be the application. If 'hls' was requested, it will be the URL for the index file.||"https://my.server.com/subdir/track1.mp3", "rtmp://server.com/application/", or "https://hls.server.com/subdir/track1.m3u8"|
|url_segment_two||string||If the protocol requested was http this will be blank. If rtmp was requested, it will be the stream name prefixed by the file format.||"mp3:subdir/track1"|
That's all there is to it. You would then feed the HTTP stream URL to your player, or if using RTMP the application and stream endpoint to the Flash player, and you should hear music.
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. 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 Groupaccount rep if you'd like to discuss options around this.