Skip to content

Integration

Jump to bottom Edit New page
Stefano Gottardo edited this page Oct 6, 2024 · 115 revisions

To play multi bitrate streams from an add-on you need to set a few ListItem properties in order to tell Kodi

  • that inputstream.adaptive should be selected for demuxing the stream
  • how to handle the decryption (if the stream is encrypted with or without DRM)

TO LEARN HOW TO CONFIGURE AND PLAY ENCRYPTED VIDEOS, GO TO Integration DRM PAGE.

Examples for Kodi v19 and above

Here we provide examples for python add-ons but can also be adapted for binary add-ons.

Play unencrypted video stream

listitem = xbmcgui.ListItem(path='https://www.videoservice.com/manifest.mpd', offscreen=True)

# These two lines are needed to prevent the HTTP HEAD request from Kodi core, used to determine the mimetype
listitem.setMimeType('application/dash+xml')
listitem.setContentLookup(False)

listitem.setProperty('inputstream', 'inputstream.adaptive')
listitem.setProperty('inputstream.adaptive.manifest_type', 'mpd') # Deprecated on Kodi 21, removed on Kodi 22

xbmcplugin.setResolvedUrl(pluginhandle, True, listitem=listitem)

Play unencrypted video stream - STRM playlist file example

#KODIPROP:inputstream=inputstream.adaptive
#KODIPROP:inputstream.adaptive.manifest_type=mpd
#KODIPROP:mimetype=application/dash+xml
https://www.videoservice.com/manifest.mpd

Warning

Never use pipe "|" char to inject HTTP headers along an URL address such as the manifest,
e.g. https://www.videoservice.com/manifest.mpd|header=value
although it may work in some cases, it is NOT supported and will lead to unexpected errors. To add HTTP headers, use the appropriate properties such as common_headers, manifest_headers, stream_headers, and for license requests refer to DRM properties.

Properties

Deprecation meaning: When a property is marked as "deprecated" it means that a FEATURE could be REMOVED starting from the next Kodi version specified, and therefore changes are required in your add-on as soon as possible. To avoid playback problems, we recommend you to making the necessary changes to your add-on for the version of Kodi in which the property is marked as deprecated.

inputstreamaddon / inputstream

[mandatory]

This property must be set to tell kodi to use inputstream.adaptive add-on to handle the stream

For Kodi 19.x and above:

listitem.setProperty('inputstream', 'inputstream.adaptive')

For Kodi 18.x:

listitem.setProperty('inputstreamaddon', 'inputstream.adaptive')

inputstream.adaptive.manifest_type

[mandatory, until to Kodi v20]

Specify the manifest type of the media stream.

Possible values are:

  • mpd for MPEG-DASH
  • hls for HLS - HTTP Live Streaming
  • ism for Microsoft Smooth Streaming Media
listitem.setProperty('inputstream.adaptive.manifest_type', 'mpd')

WARNING: THIS PROPERTY HAS BEEN DEPRECATED ON Kodi v21, because the manifest type is now auto-detected. If you have experienced problems by removing this property by using proxy to manipulate manifests, more likely you miss to add the appropriate header in proxy manifest HTTP response, read "How to provide custom manifest and license" page for more details.

WARNING: THIS PROPERTY HAS BEEN REMOVED ON Kodi v22

inputstream.adaptive.common_headers

Specifies the HTTP headers to be used for any type of HTTP request. Although it is possible to use plaintext strings, to maintain string integrity all values should be URL encoded.

listitem.setProperty('inputstream.adaptive.common_headers', 'headername=encoded_value&User-Agent=the_user_agent&cookie=the_cookies')

Note

COOKIES: you can use "cookie" header to force set custom cookies, in this case the value must be always URL encoded.

inputstream.adaptive.manifest_params

Specifies the HTTP parameters to be used to download the manifests.

For protocols like HLS, the parameters will be applied to all manifest urls childrens.

listitem.setProperty('inputstream.adaptive.stream_params', 'paramname=value&paramname2=value2')

inputstream.adaptive.manifest_headers

Specifies the HTTP headers to be used for HTTP requests to download manifests.

listitem.setProperty('inputstream.adaptive.manifest_headers', 'headername=encoded_value&User-Agent=the_user_agent&cookie=the_cookies')

Note

COOKIES: you can use "cookie" header to force set custom cookies, in this case the value must be always URL encoded.

inputstream.adaptive.manifest_update_parameter

WARNING: PROPERTY DEPRECATED ON Kodi v21 AND REMOVED ON Kodi v22, please use manifest_upd_params instead.

This property force enable manifest updates for LIVE contents after each segment played, but usually it should be enabled automatically. In some cases could be used to solve HTTP error 404 when download the segments due to missing updates.

WARNING: Do not enable it with VOD type manifest.

To enable the manifest update

Set full as value. WARNING: THE "full" BEHAVIOUR PARAM HAS BEEN REMOVED ON Kodi v21 because now enabled by default, so when the MPD.Type is dynamic (live content).

To enable the manifest update and customize URL parameters

For MPEG-DASH manifest, you can enable and also customize the URL parameters for the manifest HTTP request.

Just set as value the URL paramenters to be add, URL encoded. In order to work you must add also the placeholder $START_NUMBER$ to set the next segment start number in the URL parameter.

Example: ?foo=bar&baz=qux&start_seq=$START_NUMBER$

listitem.setProperty('inputstream.adaptive.manifest_update_parameter', '?foo=bar&baz=qux')

NOTE: On Kodi v21 $START_NUMBER$ placeholder support has been removed.

inputstream.adaptive.manifest_upd_params

This property allows parameters to be added to the URL used to request manifest updates in LIVE content. Currently supported for DASH manifest only.

listitem.setProperty('inputstream.adaptive.manifest_upd_params', '?foo=bar&baz=qux')

inputstream.adaptive.stream_params

Specifies the HTTP parameters to be used to download streams (audio/video/subtitles).

listitem.setProperty('inputstream.adaptive.stream_params', 'paramname=value&paramname2=value2')

inputstream.adaptive.stream_headers

This property has changed over time, read carefully about its use between different versions of Kodi. Although it is possible to use plaintext strings, to maintain string integrity all values should be URL encoded.

On Kodi v19 or below:
Specifies the HTTP headers to be used to manifests and streams (audio/video/subtitles) HTTP requests.

On Kodi v20:
Specifies the HTTP headers to be used to manifests and streams (audio/video/subtitles) HTTP requests.
NOTE: Use this property to set headers to the manifests is a deprecated behaviour, use inputstream.adaptive.manifest_headers instead.

From Kodi v21 or above:
Specifies the HTTP headers to be used to streams (audio/video/subtitles) HTTP requests only.

listitem.setProperty('inputstream.adaptive.stream_headers', 'headername=encoded_value&User-Agent=the_user_agent&cookie=the_cookies')

Note

COOKIES: you can use "cookie" header to force set custom cookies, in this case the value must be always URL encoded.

inputstream.adaptive.manifest_config

Allows you to configure or change manifest behaviors. The value must be a JSON dictionary.

These are the supported config parameters:

  • timeshift_bufferlimit from v.21.4.5
    The maximum timeshift buffer depth in seconds, the default value is 4 hours (14400 secs). This is limited to avoid excessive memory consumption with very large TSB values.
    Value: an integer number

  • live_delay from v.22
    Intended for LIVE contents, set a delay from the live edge, this may be used to mitigate problems caused by a player that requests segments that do not exist yet (getting http 404 errors or causing audio buzzing). A reasonable value may be 2 to 4 times the segment duration, but not smaller than 16 seconds.

    Be aware that some manifest types already include the configuration of this property (e.g. DASH with suggestedPresentationDelay), so set this property will override the manifest value (if any).

    Value: an integer number greater or equal than 16 (default), lower values are so ignored.

HLS manifest parameters:

  • hls_ignore_endlist from v.21.4.6
    Ignore EXT-X-ENDLIST tags. Faulty live streaming services may use this tag inappropriately, thus stopping playback although it is not finished.
    Value: true, false

  • hls_fix_mediasequence from v.21.4.6
    Faulty live streaming services may provide malformed EXT-X-MEDIA-SEQUENCE values on manifest updates. Enabling this parameter will attempt to correct the value by finding the corresponding segment in the updated playlist referring to the PTS value of the segment provided by the EXT-X-PROGRAM-DATE-TIME tag. In order to work the manifest must provide the EXT-X-PROGRAM-DATE-TIME tag. This can help improve playback, but some side effects can still occur such as segments played multiple times, playback freezes, periods switched before the end of their playback, due to the impossibility of determining the right sequence.
    Value: true, false

  • hls_fix_discsequence from v.21.4.6
    Faulty live streaming services may provide malformed EXT-X-DISCONTINUITY-SEQUENCE values on manifest updates. Enabling this parameter will attempt to correct the value by checking whether a segment PTS falls within an existing period, if found will use that sequence number to correct the EXT-X-DISCONTINUITY-SEQUENCE value. In order to work the manifest must provide the EXT-X-PROGRAM-DATE-TIME tag. This can help improve playback, but some side effects can still occur such as segments played multiple times, playback freezes, periods switched before the end of their playback, due to the impossibility of determining the right sequence.
    Value: true, false

Following example use string, but with python its recommended to use json.dumps.

listitem.setProperty('inputstream.adaptive.manifest_config', '{"timeshift_bufferlimit":14400,"hls_ignore_endlist":true}')

inputstream.adaptive.play_timeshift_buffer

Allow to start playing a LIVE stream from the beginning of the buffer instead of its end, useful for example for sports channels.

Possible values are: true / false (default)

listitem.setProperty('inputstream.adaptive.play_timeshift_buffer', 'true')

inputstream.adaptive.live_delay

WARNING: PROPERTY DEPRECATED ON Kodi v22, please use inputstream.adaptive.manifest_config instead.

Intended for LIVE contents, set a delay from the live edge, this may be used to mitigate problems caused by a player that requests segments that do not exist yet (getting http 404 errors or causing audio buzzing). A reasonable value may be 2 to 4 times the segment duration, but not smaller than 16 seconds.

Be aware that some manifest types already include the configuration of this property (e.g. DASH with suggestedPresentationDelay), so set this property will override the manifest value (if any).

Possible values are: a number greater or equal than 16 (default), lower values are so ignored.

listitem.setProperty('inputstream.adaptive.live_delay', '16')

inputstream.adaptive.max_bandwidth

Allows to set the maximum stream bandwidth. The value is defined in bit/s.

This property can override the user setting Maximum bandwidth, but only if the value is less than the user setting.

listitem.setProperty('inputstream.adaptive.max_bandwidth', '100000000000')

WARNING: THIS PROPERTY HAS BEEN DEPRECATED ON Kodi v20 and is replaced by another one, see page Stream selection types properties for more details.
WARNING: THIS PROPERTY HAS BEEN REMOVED FROM Kodi v21.

inputstream.adaptive.original_audio_language

Allow to set the Kodi flag "original audio language", to the audio streams that match the specified language code.

Should be set the language code with ISO 639-1 standard (Kodi support this standard only).

NOTE: If the manifest set the original language to the streams, this not override the manifest properties.

listitem.setProperty('inputstream.adaptive.original_audio_language', 'it')

inputstream.adaptive.stream_selection_type

Allow an add-on to overridden the InputStream Adaptive "stream selection type" setting. Can be used to have customised behaviour on the selection of the audio/video quality of the streams.

Caution: This will make the "stream selection type" setting in the InputStream Adaptive setting window ineffective, so consider allowing the user choice to change this setting in your add-on.

inputstream.adaptive.config

Allows you to set miscellaneous add-on configurations. The value must be a JSON dictionary.

These are the supported config parameters:

  • internal_cookies from v.21.4.11
    Some video services require you to accept cookies and send cookies along with requests such as manifest update, segments, etc.. Most common use case is when cookies are used as authentication to get files, so at the first HTTP request of the manifest, the server send a "Set-Cookies" header from HTTP response, which the client will have to use for each subsequent request.

    Set to True to allow ISAdaptive add-on to handle cookies internally in a persistent way between HTTP sessions. If disabled (default) cookies will be handled by Kodi in a NON-persistent way, so they will be deleted after a certain period of time of video playback.

    Value: true / false (default)

  • ssl_verify_peer from v.21.4.11
    Determines whether curl verifies the authenticity of the peer's CA certificates. If set to "false" CA certificates are not loaded and verification will be skipped. This can be useful with services having faulty or expired SSL CA certificate.

    Value: true (default) / false

Following example use string, but with python its recommended to use json.dumps.

listitem.setProperty('inputstream.adaptive.config', '{"internal_cookies":true}')

If you want to improve the wiki, please inform the maintainers by opening an Issue to ask their approval, before editing.

User Documentation

Developer Documentation

Development

Clone this wiki locally