Roku Developer Program

Developers and content creators—a complete solution for growing an audience directly.
cancel
Showing results for 
Show  only  | Search instead for 
Did you mean: 
Highlighted
Level 9

Quality Dots and StreamBitrates settings

Lately, we've found that some developers have been confused about how they should be using the StreamBitrates setting in the content metadata passed to roVideoScreen. This is an important setting to set properly, as its value is used in determining how much data we need to prebuffer. The StreamBitrates setting is also used by the roVideoScreen to display the number of "quality" dots for the selected stream to the user. As mentioned in the Component Reference, the preferred implementation should provide multiple streams with multiple bitrates (ideally four) to provide a high quality user experience under a variety of network conditions. In this scenario, the number of "quality" dots displayed to the user should indicate which of the four streams was chosen for playback based on the measured bandwidth the Roku box is experiencing.

Some developers don't have the multiple encodings necessary for the best experience, and may not even know the correct bitrate for their stream. When you can't be accurate about the required bitrate for your stream, it is best to use a single stream and set the bitrate to zero. A single stream set to a bitrate of zero is a special case for the roVideoScreen where it will not display the quality dots to the user and will try to pre-buffer enough data to avoid rebuffers when playing your stream. This scenario may trade-off a little longer prebuffer phase for a better playback experience.

If you know what your actual required bitrate is, you can accurately set the StreamBitrates parameters to optimize the prebuffer startup phase and playback experience. If you don't accurately know the actual required bitrate and you only have a single stream, it is probably best to set your StreamBitrates meta-data content parameter = [0].
0 Kudos
11 Replies
Highlighted
Level 9

Re: Quality Dots and StreamBitrates settings

Another confusing thing is the units of this setting. (I too have been bitten by it).

StreamBitrates is specified in Kbps.... So, an item with 4 different encodings with bitrates of 330 Kbps, 660 Kbps, 996 Kbps, and 2Mbps will have a StreamBitrates setting of [330, 660, 996, 2048]
0 Kudos
Level 7

Re: Quality Dots and StreamBitrates settings

From the docs:
Using the StreamBitrates and StreamURLs provided in the content meta-data for the item, the roVideoScreen will automatically monitor and select the best stream based on the users measured bandwidth. If network performance changes, the system will adapt and rebuffer to stream at a different bandwidth if necessary. Note that the StreamURLs, StreamBitrates, StreamQualities and StreamStickyHttpRedirects are all arrays that are aligned with each other. For example, the first stream listed would be the 0th element of all of these arrays.

I understand that StreamURLs/StreamBitrates/etc. all need to be aligned, but does it matter if StreamBitrates is sorted or not?

Should we be adding urls/bitrates in any particular order (high->low, low->high), or does it not matter at all?

Thanks!
My Roku Channels:
Viddler - viddler.com
Tested Fan - tested.com | Jamie & Adam
This is my next - theverge.com
1080p Showcase - RIP
Whiskey Media - RIP
======================
http://www.binarymoustache.com
0 Kudos
Highlighted
Roku Employee
Roku Employee

Re: Quality Dots and StreamBitrates settings

"evilmax17" wrote:
I understand that StreamURLs/StreamBitrates/etc. all need to be aligned, but does it matter if StreamBitrates is sorted or not?

Should we be adding urls/bitrates in any particular order (high->low, low->high), or does it not matter at all?


The arrays do not need to be sorted in any particular order.

More importantly, the parallel array mechanism has been deprecated since firmware 2.6 and we encourage you to use the streams attribute of the content-meta-data structure instead. The streams attribute should be an array of roAssociativeArrays as documented in section 3.3 of the Component Reference.
0 Kudos
Highlighted
Level 7

Re: Quality Dots and StreamBitrates settings

Is there anyway to programmatically obtain what StreamBitrate or Quality dot is playing within the roVideoScreen?
0 Kudos
Highlighted
Level 7

Re: Quality Dots and StreamBitrates settings

"dustinhood" wrote:
Is there anyway to programmatically obtain what StreamBitrate or Quality dot is playing within the roVideoScreen?

Take a look at the "bandwidth.minute" log type for the roSystemLog component.
My Channels: http://roku.permanence.com - Twitter: @TheEndlessDev
Instant Watch Browser (NetflixIWB), Aquarium Screensaver (AQUARIUM), Clever Clocks Screensaver (CLEVERCLOCKS), iTunes Podcasts (ITPC), My Channels (MYCHANNELS)
0 Kudos
Highlighted
Level 7

Re: Quality Dots and StreamBitrates settings

I am currently using syslog.EnableType("bandwidth.minute") to obtain the bandwidth, how can use use syslog to get the current stream bitrate?

"TheEndless" wrote:
"dustinhood" wrote:
Is there anyway to programmatically obtain what StreamBitrate or Quality dot is playing within the roVideoScreen?

Take a look at the "bandwidth.minute" log type for the roSystemLog component.
0 Kudos
Highlighted
Level 7

Re: Quality Dots and StreamBitrates settings

"dustinhood" wrote:
I am currently using syslog.EnableType("bandwidth.minute") to obtain the bandwidth, how can use use syslog to get the current stream bitrate?

"TheEndless" wrote:
"dustinhood" wrote:
Is there anyway to programmatically obtain what StreamBitrate or Quality dot is playing within the roVideoScreen?

Take a look at the "bandwidth.minute" log type for the roSystemLog component.

My assumption was that the amount of bandwidth being used would be enough of an indication for you to determine which stream bitrate was being used. If you use the "http.connect" log type, it should give you the URL of the stream being requested when it requests it or switches bitrates, so you could possibly use the two to get the information you need.
My Channels: http://roku.permanence.com - Twitter: @TheEndlessDev
Instant Watch Browser (NetflixIWB), Aquarium Screensaver (AQUARIUM), Clever Clocks Screensaver (CLEVERCLOCKS), iTunes Podcasts (ITPC), My Channels (MYCHANNELS)
0 Kudos
Highlighted
Level 7

Re: Quality Dots and StreamBitrates settings

Okay, thanks for the tip, I will give your suggestion a try.

I also found the following: viewtopic.php?f=34&t=38689&p=254439&hilit=bitrate which relates to the isStreamStarted()

isStreamStarted()
• Event to give details about the stream that was started.
• Event Details: Type = 20, Msg = “”, Index = Seconds from Play to Start Streaming, Data = 0

Info = { url:<url of video>, StreamBitrate:<bitrate of stream>, MeasuredBitrate:<actualBitrateOfDataTransfer>, IsUnderrun:<true if streamStarted is the result of an underrun> }

"TheEndless" wrote:
My assumption was that the amount of bandwidth being used would be enough of an indication for you to determine which stream bitrate was being used. If you use the "http.connect" log type, it should give you the URL of the stream being requested when it requests it or switches bitrates, so you could possibly use the two to get the information you need.
0 Kudos
Highlighted
Level 7

Re: Quality Dots and StreamBitrates settings

For those interested this is the code to gather the current url and the current bitrate of the video playing using isStreamStarted():

if type(msg) = "roVideoScreenEvent" then
print "showVideoScreen | msg = "; msg.getMessage() " | index = "; msg.GetIndex()
if msg.isScreenClosed()
print "Screen closed"
exit while
elseif msg.isStreamStarted()
i = msg.GetInfo()
metrics.streamUrl = i.Url
metrics.streamBitrate = i.StreamBitrate
metrics.bandwidth = i.MeasuredBitrate
endif
endif


After a little testing it appears that isStreamStarted() will update at first run and anytime the stream buffers including after fast forwarding and rewinding. I have only tested this on 013.00E02207A using non HLS streams.
0 Kudos