Live Caption Vendor info

Closed Captions over HTTP for YouTube Live Streams

This document defines the format by which YouTube will get Closed Caption data.

POST Content

YouTube expects Closed Caption data to arrive in a continuous sequence of POSTs. The URL of the POST will specify the destination (the Live Stream that the closed captions will be associated with) of the data. The body of the POST will contain the time and text for the closed caption data. A line break may be indicated with <br> in the closed caption text. It has the format:

 

<UTC Time> [region / cue]
<TEXT>
<UTC Time> [region / cue]
<TEXT>
<UTC Time> [region / cue]
<TEXT>

Where

            <UTC time>                         YYYY-MM-DDTHH:MM.SS.mmm
            [region / cue]                 optional region:reg1#cue1, format TBD
            <TEXT>                                 UTF-8

 

Example:

      2012-12-24T00:00:06.873
      I'M
      2012-12-24T00:00:06.974
      SENDING
      2012-12-24T00:00:07.030
      SEVERAL
      2012-12-24T00:00:07.104
      CAPTIONS

HTTP POST Specifics for URL Query Parameters

The following table lists the required query parameters.

The following parameters are typically given by YouTube: 

 
Note:  &sparams, &expire, &signature and &key are not required when sending data to our staging servers. 
Name Description/Usage Example Fragment
id Stream ID Must be contained in all POSTs. &id=someStreamID
ns Stream name. Must be contained in all POSTs. &ns=someStreamName
sparams Must be contained in all POSTs. Must be fully specified as given on the right. &sparams=id%2Cns%2Cexpire
expire Must be contained in all POSTs. &expire=1349539164
signature Must be contained in all POSTs. &signature=564AB21...C4A9B281F.D1A68B7...062988FBA95
key Must be contained in all POSTs. Must have value yt_qc. &key=yt_qc

The following parameter must be added to the URL of every POST.

Name Description/Usage Example Fragment
seq Must be contained in all POSTs. Counter for all closed caption data posts. Counter must increase by one between posts of new caption data (it must not be increased for retries). &seq=123

Content Type

The content-type (mimetype) for all POSTs must be text/plain.

Content Data

All HTTP POSTs sent to the closed caption ingestion point must contain only closed caption data within the content body. Data must not be form encoded.

Response Codes

HTTP POSTs may return various response codes. Their meaning is:

Response Code Meaning

405

Method not allowed. Not a POST.

400

Bad request. URL failed to parse. Could be due to missing &seq query parameter or missing &id, or &ns.

403

Unauthorized. Signature invalid. Note: URLs given by YouTube front end will contain all signature info.

Request Retries

We recommend performing retries on all other codes (the above 405, 400, 403 and codes such as 408 Request Timeout, 500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable, 504 Gateway Timeout).

All HTTP POST requests should be performed with a timeout. If a request times out, it should be retried.

When performing retry requests, use randomized binary exponential backoff: Wait a random period between [0...100] milliseconds and retry; if that doesn't work, wait a random period between [0..200] milliseconds and retry; if that doesn't work, wait a random period between [0..400] milliseconds and retry and so on. You should retry until it makes more sense to move on to the next closed caption packet (TBD, perhaps after 5 seconds).

For more info, go to binary exponential backoff

Empty HTTP POST as Heartbeat

HTTP POSTs with an empty body, or an empty text line after the timestamp line, MAY be used to perform a heartbeat function. The POSTs will have no effect on the caption text stream, but client software may verify that the HTTP connection to the Google closed caption server is working, and the Google closed caption server can verify that it's being driven by a client.

HTTP POST returns Timestamp

A Timestamp value is present in the POST return body and corresponds to the time the POST was processed. It may be used to correct the local clock on a client driving the server. It's recommended that this value be used since local clocks are often poorly synchronized.

Example returned timestamp:

     2012-12-24T00:00:06.873 

URLs given by YouTube 

Ingestion URLs will be given by the YouTube front page. An example URL is:

http://upload.youtube.com/closedcaption?sparams=id%2Cns%2Cexpire&expire=1352689249&key=yt_qc&signature=0D3B147BAFA18DDE62B304AE429834186FC5E5BA.8C9162D7B10B7DED35FBD65D4BC8E5AE3AF98A4D&ns=yt-ems-t&id=HckQ0lctwDyDn3SXfWUwHw1350097249388495&seq=1

For the staging server, the following is a valid example URL:
http://upload.youtube.com/closedcaption?ns=my_name&id=12345&seq=1&staging=1
 

Notes: The URL search parameters &seq has to be added to the above provided URL. 

Example POST

POST /closedcaption?sparams=id%2Cns%2Cexpire&
expire=1352689249&key=yt_qc&signature=0D3B147BAFA18DDE62B304AE429834186FC5E5BA.8C9162D7B10B7DED35FBD65D4BC8E5AE3AF98A4D&ns=yt-ems-t&id=HckQ0lctwDyDn3SXfWUwHw1350097249388495&seq=42

Host: localhost:8000
Accept: */*
Content-Type: text/plain
Content-Length: 127970

2012-12-24T00:00:06.873 region:reg1#cue1
I'M, FOR THE MOMENT,
2012-12-24T00:00:06.974 region:reg1#cue1
AT
2012-12-24T00:00:07.030 region:reg1#cue1
THE
2012-12-24T00:00:07.104 region:reg1#cue1
LEFT

Sync

The YouTube live control room will build a feature for the event owner to change the captions by +/- x seconds. But, it would also be useful to build a control in the captioning software to adjust for lead/lag time. Make sure that this control only applies to the YouTube output.

Was this helpful?
How can we improve it?
false
Search
Clear search
Close search
Google apps
Main menu
Search Help Center
true
59
false