============================================================== DUNE HD STB -- MEDIA URL CONCEPT ============================================================== Overview -------- The concept of "media_url" is widely used in Dune HD media players for various purposes. "media_url" is a string which typically points to some media content that can be played, optionally with some parameters which influence the playback. "media_url" can also point to some graphic resources (e.g. icon), and to some other kinds of files/resources (e.g. web page URL, optionally with some parameters which influence the way it should be handled by the web browser, or FlashLite application file, optionally with some parameters which influence the way it should be launched and run). "media_url" can be used in various contexts, in particular: - Playlist files (e.g. .m3u). - "dune_folder.txt" files. - Dune HD IP Control API (by external applications). - Dune HD PHP Plugins API (by PHP plugins). - Dune HD FlashLite API (by FlashLite applications). - Dune HD STB API (by HTML+JavaScript and DirectFB applications). Supported "media_url" for playback from network/Internet -------------------------------------------------------- Multicast UDP/TS (raw-UDP or RTP-over-UDP), Live TV/radio: ---------------------------------------------------------- Syntax: udp://@{multicast-address}:{port} Example: udp://@239.0.1.1:1234 DRMs supported: Verimatrix IPTV client. NOTE: May require special firmware build and/or special configuration (details are available upon request). HTTP/TS, Live TV/radio: -------------------------- Syntax: http://ts://{host}[:{port}][/{path}] Example: http://ts://myserver.com/my_live_stream.ts NOTE: This is plain live MPEG2-TS stream over HTTP. Seek and duration detection are not supported. DRMs supported: Verimatrix IPTV client. NOTE: May require special firmware build and/or special configuration (details are available upon request). HLS (Apple HTTP Live Streaming), VOD or Live TV/radio: ------------------------------------------------------ Syntax: http://{host}[:{port}][/{path}].m3u8[?{args}] Example: http://myserver.com/my_content.m3u8 NOTE: If HLS HTTP URL neither ends with ".m3u8" nor contains ".m3u8?", you can use "protocol:hls" parameter to force the system to handle the URL as HLS; example: http://myserver.com/my_content|||dune_params|||protocol:hls NOTE: HLS audio streams based on raw-audio HLS segments are not supported; HLS audio streams with HLS segments based on MPEG-TS are supported. DRMs supported: AES generic encryption. NOTE: HLS key is retrieved directly using the URL provided by the server. If it is needed to pass certain parameters to the server when retrieving HLS key, it is possible to add these parameters to the query part of the HLS URL using "hls_key_url_add_query" parameter (see "Parameters for playback URLs" section). Verimatrix Web client. NOTE: May require special firmware build and/or special configuration (details are available upon request). HTTP/MP4, VOD: -------------- Syntax: http://mp4://{host}[:{port}][/{path}] Example: http://mp4://myserver.com/my_file.mp4 NOTE: This is a special MP4 playback mode intended for OTT (over Internet) connections. DRMs supported: None. RTSP/TS (RTSP+RTP or RTSP-over-TCP), VOD or Live TV/radio: ---------------------------------------------------------- Syntax: rtsp://{host}[:{port}][/{path}] Example: rtsp://myserver.com/my_content NOTE: Only MPEG2-TS streams are supported. MPEG2-TS stream should be either streamed via RTP (RTSP+RTP), or encapsulated into RTSP TCP connection (RTP-TCP). DRMs supported: Verimatrix IPTV client. NOTE: May require special firmware build and/or special configuration (details are available upon request). MMS/ASF (MMS-over-TCP or MMS-over-HTTP), Live TV/radio: ------------------------------------------------------- Syntax: mms[h]://{host}[:{port}][/{path}] Example: mms://myserver.com/my_radio_stream mmsh://myserver.com/my_radio_stream NOTE: Rarely used and not well tested. DRMs supported: None. HTTP generic (any file, audio streaming, playlist): --------------------------------------------------- Syntax: http://{host}[:{port}][/{path}] Example: http://myserver.com/my_file.mkv http://myserver.com/my_file.mp3 http://myserver.com/my_radio_stream.mp3 http://myserver.com/my_radio_stream http://myserver.com/my_playlist.m3u NOTE: HTTP VOD playback may not work well over slow Internet connections (buffering may be slow), and is mostly intended for local networks (e.g. playback from UPnP server). For HTTP VOD playback over Internet, it is recommended to use MP4 container and "http://mp4://" syntax. DRMs supported: None. Supported "media_url" for files on filesystem-based storages ------------------------------------------------------------ SMB, any file (e.g. video/audio/photo) or folder: ------------------------------------------------- Syntax: smb://[{user}[:{password}]@]{host}/{share}/{path} Example: smb://192.168.1.1/myshare/path/to/file.mkv smb://admin@192.168.1.1/myshare/path/to/file.mkv smb://admin:123456@192.168.1.1/myshare/path/to/file.mkv smb://admin:123456@192.168.1.1/myshare/path/to/MY_FOLDER smb://admin:123456@192.168.1.1/myshare/path/to/my_playlist.m3u NFS (UDP or NFS), any file (e.g. video/audio/photo) or folder: -------------------------------------------------------------- Syntax: nfs[-tcp|-udp]://{host}[:/{nfs-export-path}]:/{path} Example: nfs://192.168.1.1:/export1:/path/to/file.mkv nfs://192.168.1.1:/export1/path/to/file.mkv nfs://192.168.1.1:/export1/path/to/MY_FOLDER nfs://192.168.1.1:/export1/path/to/my_playlist.m3u nfs-tcp://192.168.1.1:/export1/path/to/my_playlist.m3u NOTE: If {nfs-export-path} is not specified, it is attempted to be deduced from {path}. When possible, it is recommended to explicitly specify {nfs-export-path} for better performance. NOTE: The default is UDP. I.e. "nfs://" is equivelent to "nfs-udp://". Content on a specified local storage device: -------------------------------------------- Syntax: storage_name://{storage-name}/{path} storage_label://{storage-label}/{path} storage_uuid://{storage-uuid}/{path} main_storage://{path} (*) available in firmware 130319_b6+ Example: storage_name://MY_FLASH_DRIVE/path/to/file.mkv storage_label://MY_FLASH_DRIVE/path/to/file.mkv storage_uuid://0123456789abcdef012345/path/to/file.mkv main_storage://path/tofile.mkv NOTE: See here for more information about storage name, storage label, and storage uuid: http://dune-hd.com/firmware/misc/dune_folder_howto.txt Content on the same local storage device or the same SMB/NFS share: ------------------------------------------------------------------- Syntax: {path} /{path} Example: file.mkv some_folder/file.mkv ../../../some_folder/other_folder/file.mkv /path/to/file.mkv NOTE: Such URLs may only be used in "dune_folder.txt" or playlist files, located on a local storage device, or on a SMB/NFS share. Supported "media_url" for playback from DVB-S/S2/T/T2/C tuner ------------------------------------------------------------- See here: http://files.dune-hd.com/partners/sdk/dvb.txt Supported "media_url" for special cases --------------------------------------- File which is a part of plugin: ------------------------------- Syntax: plugin_file:///{path-relative-to-plugin-root-folder} Example: plugin_file:///icons/icon.png NOTE: Such URLs may only be used in context of plugin. File from current GUI skin: --------------------------- Syntax: gui_skin://{path-relative-to-skin-root-folder} Example: gui_skin://large_icons/tv.aai NOTE: Such URLs may only be used in contexts, where some GUI resource (such as icon) is expected. Supported "media_url" for special actions ----------------------------------------- Launch FlashLite application: ----------------------------- Syntax: swf://{HTTP-or-file-URL}[:::{parameters}] Example: swf://http://myserver.com/path/to/app.swf swf://http://myserver.com/path/to/app:::id=29 swf://../../my_folder/file.swf:::id=29 swf://plugin_file://app.swf:::id=29 NOTE: See "Parameters for SWF URLs" section. Launch web browser and load HTML page from given URL: ----------------------------------------------------- Syntax: www://{HTTP-or-file-URL}[:::{parameters}] Example: www://http://myserver.com www://http://myserver.com:::fullscreen=1&webapp_keys=1&zoom_level=100&overscan=0&background_color=black www://plugin_file://index.html:::fullscreen=1&webapp_keys=1&zoom_level=100&overscan=0&background_color=black www://127.0.0.1/cgi-bin/plugins/my_plugin/a.cgi?arg=value:::fullscreen=1 NOTE: See "Parameters for WWW URLs" section. Launch some embedded applications: ---------------------------------- (*) available in firmware 130819_b8+ Common syntax: embedded_app://{name=}{param1=value1}... Supported application names: network_browser setup file_browser main_menu Network browser embedded app parameters: keep_position=0|1, default=0 caption=, default=selected id=, default=selected Setup embedded app parameters: kind=, default=setup keep_position=0|1, default=0 caption=, default=selected id=, default=selected File browser embedded app parameters: url=, mandatory caption=, default=selected id=, default=selected Main menu embedded app parameters: keep_position=0|1, default=0 caption=, default=selected id=, default=selected Examples: embedded_app://{name=network_browser}{caption=My Network}{keep_position=1} embedded_app://{name=setup}{kind=video}{keep_position=1}{caption=Video Settings} embedded_app://{name=file_browser}{url=smb://192.168.1.1/myshare/path/to/file.mkv} embedded_app://{name=main_menu} Parameters for SWF URLs ----------------------- See here: http://dune-hd.com/firmware/flash/flashlite_info.txt "Media URL for SWF file" Parameters for WWW URLs ----------------------- See here: http://files.dune-hd.com/partners/sdk/html_apps.txt "Web browser start parameters" Parameters for playback URLs ---------------------------- Syntax: {media_url}|||dune_params|||param1:value1,...,paramN:valueN Example: http://myserver.com/my_content|||dune_params|||protocol:hls,buffering_ms:2000 Supported parameters: rtsp_tcp:0|1 (default: 0) Only for RTSP URLs. 0 = RTSP+RTP is preferred, RTSP-TCP is autodetected when possible. 1 = RTSP-TCP is forced. rtsp_seek_via_reopen:0|1 (default: 1) Only for RTSP URLs. 0 = seek is performed w/o full RTSP stream reopen. 1 = seek is performed with full RTSP stream reopen (needed/useful for some RTSP servers). protocol:hls (default: autodetect) NOTE: Other values are not supported. Force HLS protocol for HTTP URLs. Needed when HTTP URL neither ends with ".m3u8" nor contains ".m3u8?". hls_initial_bandwidth:low|high|auto|auto_high (default: according to user settings, which is "auto" by default) Only for HLS URLs. low: On HLS URL playback startup, the lowest possible bitrate is used initially. high: On HLS URL playback startup, the highest possible bitrate is used initially. auto: On HLS URL playback startup, the bitrate corresponding to the latest actual bitrate is used initially, or the lowest possible bitrate if there is no remembered latest actual bitrate. This is the recommended option. auto_high: On HLS URL playback startup, the bitrate corresponding to the latest actual bitrate is used initially, or the highest possible bitrate if there is no remembered latest actual bitrate. hls_key_url_add_query:{string} (default: none) Only for HLS URLs. Only when AES encryption is used. When specified, {string} is added to the query part of HLS AES key URL which is used to retrieve HLS AES key. If the key URL already contains the query part, '&' is added before {string}, otherwise '?' is added before {string}. Single comma is not allowed inside the string because it has the meaning of parameters delimiter. To specify a comma use double comma instead so that "aaa=bbb,,ccc" means "aaa=bbb,ccc". Example: http://myserver.com/a.m3u8|||dune_params|||hls_key_url_add_query:auth_token=12345678 hls_bw_strategy:0|1 (default: 0) Only for HLS URLs. 0 means current variant bandwidth switching strategy when player tries to maximize quality making switches even when connection bandwidth is not sufficient but buffering state allows to temporarily play a higher bitrate stream for some time. Setting to 1 changes HLS bandwidth variants switching strategy so that switching between variants is less frequent and is performed only when current connection bandwidth is more than a selected new variant. hls_sticky_live:0|1 (default: 1) Only for HLS URLs. This enables a specific workaround for situations when in a sliding window playlist (live transmission) an end-list tag appears due to some software glitch. If this parameter is on the end-list tag is ignored in such a case. This parameter does not affect HLS VOD playback. enable_seek:0|1 (default: 1) NOTE: Is currently supported for HLS protocol only. 0 = time seek operations are disabled. 1 = time seek operations are enabled (when possible, i.e. for VOD content). deint_mode:off|bob|adaptive|adaptive_plus (default: according to user-defined settings) (*) adaptive_plus setting is available in firmware 150318_b9+. Allows to explicitly specify the desired deinterlacing mode. Useful e.g. in the following case: an application performs playback of an IPTV channel with interlaced video stream and wants to ensure "adaptive" deinterlacing mode for this IPTV channel, even if the user-defined setting is "bob". force_deint:off|tff|bff|use_mpeg2_pseq (default: use_mpeg2_pseq for MPEG-TS, off otherwise) Specifies if deinterlacing should be forced. off: Enable deinterlacing only when the content is recognized as interlaced. tff: Force deinterlacing, assuming top-field-first content. bff: Force deinterlacing, assuming bottom-field-first content. use_mpeg2_pseq: Automatically force deinterlacing for MPEG2-video streams which cliam that they are not interlaced, but are actually interlaced, using some heuristics. NOTE: in many cases, using "deint_mode:adaptive,force_deint:use_mpeg2_pseq" would give the best results. buffering_ms:1..60000 (default: according to user-defined settings) Only for MPEG-TS streams (HTTP/TS, HLS, RTSP, UDP multicast, DVB). Specifies buffering period (buffer size) in milliseconds. NOTE: For HLS, the impact of this parameter on playback startup depends highly on the bandwidth, and it may be hardly noticeable if the bandwidth is much higher than the actual stream bitrate (since the server typically sends HLS chunks to the client with the maximum possible speed). vmx_iptv_enh_buffering:0|1 (default: 1) Only for multicast URLs. Allows to specify if the enhanced buffering for Verimatrix IPTV is used or not. Enabling (setting to 1) speeds up channel switching. Disabling (setting to 0) may be useful for troubleshooting and/or on very high bitrates. Setting this option to 0 sets PSI optimization (for multicast) to off overriding it. psi_opt:0|1|2 (default: 1 for HLS, 2 for RTSP, 0 otherwise) Only for MPEG-TS streams (HTTP/TS, HLS, RTSP, UDP multicast). Specifies if some optimizations should be enabled when opening MPEG/TS stream: 0 = no optimizations, 1 = some optimizations, 2 = more aggressive optimizations. fast_prebuf:0|1 (default: 0) Only for multicast MPEG-TS streams. Enables fast playback startup for multicast MPEG-TS streams in specific cases. Mostly intended for specific usages (local multicast proxy enabling fast channel switch), is likely to cause buffering glitches when used for ordinary broadcasts. ll_prebuf_for_http_ts:0|1 (default: 0) Only for MPEG-TS streams over HTTP/TS. Enables fast playback startup (low latency prebuffering). Depends on MPEG-TS stream specifics and may not work in all cases. It is intended to be used only for very stable streaming sources. NOTE: it is not recommended to set buffering_ms lower than 300 when this option is on. Specifying a high value of buffering_ms when this option is on is impractical. ll_display_for_http_ts:0|1 (default: 0) Only for MPEG-TS streams over HTTP/TS. Enables special low-latency display mode when each video frame is shown almost as soon as it is received completely. This option is intended to be used with streams specially optimized for low latency playback. ll_display_for_http_ts_audio_delay (default: 100) Only for MPEG-TS streams over HTTP/TS. Specifies audio delay in milliseconds relative to video when ll_display_for_http_ts is 1. It is intended to get stable audio playback at the expense of some lag. buffering_skip_to_keyframe:0|1 (default: 0) Only for MPEG-TS streams (HTTP/TS, HLS, RTSP, UDP multicast). If enabled specifies that on playback start some (audio) data for which there is no playable video is skipped. Has no effect for VOD and radio (audio-only streams). This option has effect for HTTP/TS only when ll_prebuf_for_http_ts:1. This option is intended to be used only when startup of a stream is faster than real time, like for HLS and (when server allows) for HTTP/TS when playback frequently starts far from a keyframe so a lot of audio is played back before any picture appears. It is not recommended to use this option unless needed. pcr:0|1 (default: 0 for local files, 1 otherwise) Only for local MPEG-TS files, HLS streams, and MPEG-TS streams over HTTP/TS. Specifies if MPEG-TS PCR information should be used by the STB for clock synchronization during playback. Disabling PCR usage could be helpful in case if PCR information in MPEG-TS streams contains errors or abnormalities which prevent correct playback of the stream. This option is not supported for multicast, DVB, RTSP streams (in these cases, PCR information is always used). Setting this option to 0 changes buffering behaviour. It is not recommended to use this option unless absolutely needed. keep_pic:0|1 (default: 1) For MPEG-TS media. Specifies if the last shown frame should be kept on screen (instead of showing black screen) while switching between MPEG-TS streams. Has effect only when both MPEG-TS streams are streamed in a way allowing the system to optimize streams switching (e.g. both streams are multicast streams, or both streams are HLS streams, etc) and avoid full playback engine restart; when full playback engine restart happens, blank screen is shown anyway. keep_audio_pid:0|1 (default: 0) For MPEG-TS media. When enabled forces keeping the same audio PID when program contents change during playback and not choosing it from scratch again according to language preferences. This is intended as a specific workaround for streaming data. recording_encryption:0|1 (default: 0) Only for MPEG-TS streams (HLS, UDP multicast, DVB). When enabled forces LPVR recordings to be written to disk in encrypted form. Encrypted recordings can be played only on the same STB where they were created. pcr_disc_ms:1... (default: 10000000 for HLS, 10000 otherwise) (*) Available in firmware 140223_b9+, 140424_b8+. Only for MPEG-TS streams (HLS, RTSP, HTTP/TS, not for multicast/DVB). Specifies PCR discontinuity recovery mechanism sensitivity in milliseconds: if PCR discontinuity is larger than this threshold then demux makes appropriate restarts with fast recovery, otherwise there will be a wait with the time equal to the discontinuity PCR gap. PCR discontinuity recovery does not work with pcr:0 or when PCR is really absent in a stream. cancel_ll_prebuf:0|1 (default: 1) (*) Available in firmware 140312_b9+. Only for multicast/DVB. Only for 867x+ platforms. If set to 1 enables early cancelling low latency prebuffering if it is considered that there is already enough data buffered. Try disabling (restoring an older behaviour) if audio is (generally sometimes) missing after switching channels. shorter_ll_prebuf:0|1 (default: 0) (*) Available in firmware 140312_b9+. Only for multicast/DVB. Only for 867x+ platforms. If set to 1 enables shortening low latency prebuffering by a certain time that is estimated as the duration of already buffered data. Requires cancel_ll_prebuf:1. This parameter has a mostly experimental status yet. hls_seek_live:0|1 (default: 0) (*) Available in firmware 140226_b9+. Only for HLS. Enables seek, pausing and an appropriate duration/position reporting when playing live (sliding window) HLS assets. Behavior introduced since firmware 150610_r10+: - The allowed seek-range ([0, duration]) excludes a few first and last HLS segments, in order to enforce only safe seeks and ensure that buffering and clock synchronization work properly. - If live HLS stream does not have enough segments to enable safe seeks (typically takes place when there are less than 6 segments), the stream is considered to be non-seekable despite the hls_seek_live setting (and API reports that the stream has no duration, same way as e.g. for multicast streams). - Pause is allowed for any live HLS streams even when the stream is considered to be non-seekable or hls_seek_live is not specified. Works the same way as e.g. pause for multicast: freezes the current picture, continues live stream playback on resume. - Playback position is reported and treated in a way which allows to easily map it to the offset between the live stream and the currently played timeshifted stream. - The following formula is used: position = duration - offset - position = 0: the maximum possible offset from the live stream. - position = duration: the live stream is played. - On playback start, position is set to duration. - During playback, position changes only as the result of seek and pause operations: - Seek operation sets the position to the specified value (rounded to segment length). - When playback is paused, position decreases by 1 each second until it reaches zero. - If playback is paused for a period longer than the length of the allowed seek-range, the position is kept equal to zero; on resume, the playback continues from the zero position. - During normal playback, position does not change. - In general, the reported position is always is in range [0, duration]. However, in some specific corner cases, the reported position might temporarily exceed the reported duration; the application is recommended to handle these cases the same way as if the reported position was equal to the reported duration. - An attempt to seek to a position exceeding duration is handled the same way as seeking to the position equal to duration, i.e. returning to the live stream. hls_forced_type:vod/event/sliding_window (default: according to asset) (*) Available in firmware 140225_b9+. Only for HLS. Allows to assume a different asset type. Takes precedence over the hls_sticky_live parameter. Does NOT allow to play an asset without end-list as VoD. This parameter is mostly intended to properly handle event assets without explicit event type specification. hls_v4_audio:1 (default: 0) (*) Available in firmware 131009_b9+. Only for HLS. Enables highly limited support for HLS v4 audio tracks in appropriate assets. program_number:1... (default: autodetect) (*) Available in firmware 140218_b9+. For all MPEG-TS playback. Allows to specify explicitly program number (service id). Useful for multiple-program stream playback and as a workaround in the case when PAT specifies several program but only one is present and that one is not the first one. Specification of a non-existing program will result in not choosing any program thus playing no audio and no video. Takes precedence over program number in DVB URL. ss_for_http_ts:1 (default: 0) (*) Available in firmware 140814_b9+. Only for MPEG-TS streams over HTTP/TS. Enables streams switching optimization between two HTTP/TS streams (avoid full engine restart). Has effect only when both MPEG-TS streams are streamed via HTTP/TS and both media url has this option set to 1. vmx_drm:0|1 (default: according to media and requested DRM) (*) Available in firmware 150321_r10+. For MPEG-TS playback where Verimatrix IPTV and Verimatrix Web are applicable. Overrides the current Verimatrix DRM status, if possible. Allows to disable Verimatrix IPTV and to disable or enable Verimatrix Web (change the way the keys are retrieved). item_id:0... (default: autodetect or user choice) (*) Available in firmware 150312_r10+. For playback of certain multi-item assets. Allows to choose an item in such an asset. item_position:0... (default: 0 or bookmark) (*) Available in firmware 150312_r10+. For playback of certain multi-item assets. Allows to choose a resume position in the item to play in such an asset when item_id is specified.