Creating streaming URL

You can generate streaming URL without querying the API.

There is 2 steps:

  • generating the URL
  • signing the URL to protect it

Embed URL

The embed URL is the easiest way to add videos to your own website using the Dailymotion Cloud video player. This solution will work on every desktop browser and iPhone/iPad devices.

The generic format of an embed URL is:

http://api.dmcloud.net/embed/<user_id>/<media_id>?auth=<auth_token>&skin=<skin_id>

URL Elements:

  • user_id: this is your user_id (eg: 4c1a4d3edede832bfd000003)
  • media_id: this is the id of the media (eg: 4c922386dede830447000009)
  • auth_token: the authentication token describe in the section about URL signing
  • skin_id: (optional) the id of the custom skin for the video player

You can optionaly select a custom Player using the query string argument skin, either a built-in skin eg: skin=modern1 or your own skin eg: skin=4c922386dede830447005923.

The embed URL must be referenced in an iframe, here is an example HTML code:

<iframe width="848" height="480" frameborder="0" scrolling="no" src="http://api.dmcloud.net/embed/<user_id>/<media_id>?auth=<auth_token>&skin=<skin_id>"></iframe>

Media URL

The media URLs are usefull when you want to implement your own video player or directly access each media assets.

The generic format of a media URL is:

http://cdn.dmcloud.net/route/<user_id>/<media_id>/<asset_name>.<asset_extension>?auth=<auth_token>

URL Elements:

  • user_id: this is your user_id (eg: 4c1a4d3edede832bfd000003)
  • media_id: this is the id of the media (eg: 4c922386dede830447000009)
  • auth_token: the authentication token describe in the section about URL signing
  • asset_name: the name of the asset you want to stream (eg: mp4_h264_aac)
  • asset_extension: the extension of the asset, most of the time it is the first part of the asset name (eg: mp4)

If you want to provide an URL for download purpose you need to add extra parameters to the query string, because streaming are rate limited. You must add throttle=0&filename=<filename> to the media URL query string, filename is the name under which the file will be saved on the client desktop.

Signing streaming URL

To sign a URL, the client needs a secret shared with Dailymotion Cloud. This secret is call client secret and is available in the back-office interface.

A signature is generated as follow:

md5sum = MD5(<sec-level><url-no-query><expires><nonce><secret><sec-data>[<pub-sec-data>])
signed_url = <url>?auth=<expires>-<sec>-<nonce>-<md5sum>[-<pub-sec-data>]
  • expires: An expiration timestamp.
  • sec-level: A security level mask.
  • url-no-query: The URL without the query-string.
  • nonce: A 8 characters-long random alphanumeric lowercase string to make the signature unique.
  • secret: The client secret.
  • sec-data: If sec-level doesn’t have the DELEGATED bit activated, this component contains concatenated informations for all activated sec levels. See Security Levels bellow.
  • pub-sec-data: Some sec level data have to be passed in clear in the signature. To generate this component the parameters are serialized using x-www-form-urlencoded, compressed with gzip and encoded in base64.

The sec-level, url-no-query, expires, nonce, secret and optional params are concatenated as a string and an hexadecimal MD5 checksum is generated from the result. This checksum is the concatenated to other info separated by a dash and added to the query of the URL to sign using the ‘auth’ parameter.

Security Levels

The client must choose a security level for the signature. Security level defines the machanism used by Dailymotion Cloud architecture to ensure the signed URL will be used by a single end-user. The different security levels are:

  • None: The signed URL will be valid for everyone
  • ASNUM: The signed URL will only be valid for the AS of the end-user. The ASNUM (for Autonomous System Number) stands for the network identification, each ISP have a different ASNUM for instance.
  • IP: The signed URL will only be valid for the IP of the end-user. This security level may wrongly block some users which have their internet access load-balanced between several proxies. This is the case in some office network or some ISPs.
  • User-Agent: Used in addition to one of the two former levels, this level a limit on the exact user-agent of the end-user. This is more secure but in some specific condition may lead to wrongly blocked users.
  • Use Once: The signed URL will only be usable once. Note: should not be used with stream URLs.
  • Country: The URL can only be queried from specified countrie(s). The rule can be reversed to allow all countries except some.
  • Referer: The URL can only be queried if the Referer HTTP header contains a specified value. If the URL contains a Referer header with a different value, the request is refused. If the Referer header is missing, the request is accepted in order to prevent from false positives as some browsers, anti-virus or enterprise proxies may remove this header.
  • Delegate: This option instructs the signing algorithm that security level information won’t be embeded into the signature but gathered and lock at the first use (see First Access Locking Security Model below)
Name Mask Data
None 0 None
Delegate 1 << 0 None
ASNUM 1 << 1 The number part of the end-user AS prefixed by the ‘AS’ string (ie: as=AS41690)
IP 1 << 2 The end-user quad dotted IP address (ie: ip=195.8.215.138)
User-Agent 1 << 3 The end-user browser user-agent (parameter name is ua)
Use Once 1 << 4 None
Country 1 << 5 A list of 2 characters long country codes in lowercase by comas. If the list starts with a dash, the rule is inverted (ie: cc=fr,gb,de or cc=-fr,it). This data have to be stored in pub-sec-data component
Referer 1 << 6 A list of URL prefixes separated by spaces stored in the pub-sec-data component (ex: rf=http;//domain.com/a/+http:/domain.com/b/).

Which security level to choose for which usage

In general, the None security level should never be used for video stream URLs. This security level should only be used for public embed video URLs distributed using the Dailymotion Cloud’s player or via a player using the Dailymotion Cloud player component (payload).

The ASNUM security level is recommended for most use-cases as it delivers a good tradeoff between security and compatibility. When the client choose the ASNUM security level, the Delegate option have to be activated as the client as not secure way to determine the ASNUM of the end-user. If more security is need, the ASNUM + User-Agent security level should be first considered. The by IP security level is not advised as it may prevent end-user behind load-balanced transparent proxies from using the service efficiently.

For more complexe needs, it is possible to restrict a video or a player to a list of countries. The list of countries is added to the additional data of the signature with the cc key and is a list of 2 characters country codes separated by comas (ex: fr,gb,de). If the list starts with a dash, the whole list is treated as a blacklist instead of a whitelist, i.e.: the all countries are allowed except ones listed.

Finally, Referer based security level is available for embed player protection (it is meaningless for streams). This level of security isn’t very robust but is very easy to use. It only needs a list of URL prefixes passed in the public security data parameter with the rf parameter name and separated by spaces. If the delegated mode is used, the full URL (with query-string) of the first request will be used to lock the URL.

First Access Locking Security Model

Signed URL can be limited to the end-user’s ASNUM, IP or User-Agent by the client. The client may not have the same view those end-user information as Dailymotion Cloud, especially for ASNUM which is based on a frequently updated database of IP block -> ASNUM correspondances.

To prevent from false positive end-user locking, the client have the choice to not embed those information in the signature, but only instruct the chosen security level as explain in the previous section “Generate a Signed URL”. It is the first time the Dailymotion Cloud server verify this signature that the security level will be stored and enforced for subsequent requests. This is the reason the signature contains a nonce, to ensure each signature are unique.

Upon the first signed URL request from the end-user with a security level other than “None”, the Dailymotion Cloud servers will store the signature together with the related security parameters of the chosen level when the Delegate security option is present. For instance, if the security level is ASNUM + User-Agent + Delegate, the Dailymotion Cloud server will gather end-user ASNUM and user-agent, and store it associated with the URL signature.

On the subsequent requests, the server will first check if the signature is present in the database, and will ensure the ASNUM and User-Agent information are equal to the current end-user’s. If something changed, access is forbidden.