3Play Media: Docs

Live Auto Captioning

Order and Manage Live Automated Captioning with 3Play Media (contact your 3Play Account Manager for module access)

Please note that cancelling or updating live auto caption services is not available after 1 minute before the start time.

Please also note that the stream URL for live auto caption services must be available within 15 minutes of the start time.

Object Representation

Unless otherwise specified, all routes return the following data structure in the data key.

Name Type Description
id Integer ID of your live auto caption
media_file_id Integer ID of the 3Play Media file that your live auto caption belongs to
threeplay_transcript_id Integer ID of the 3Play Transcript that your live auto caption produces, needed for downloading
language_id Integer Language ID of the media file
embed_code String iFrame embed code for the live auto caption plugin
js_embed_code String Javascript embed code for the live auto caption plugin
external_webpage_with_captions_url String Link to an externally hosted webpage, with captions for the event
public_id String Custom ID of the live auto caption, which can be used to modify an existing plugin
status String Status of live auto captioning Service
stream_url String Stream URL that the live stream is or will be consuming. This must begin with 'rtmp://'
start_time DateTime Scheduled start time of the live auto caption
latency Integer Target delay (in milliseconds) for the live captions to be available (more latency typically results in more accuracy)
offensive_words_sensitivity Integer More sensitivity (from 0-3) causes more words to be elided
event_wait_time Integer Amount of time (in minutes) for our system to wait after start_time if no audio is detected, before event is failed.
event_max_time Integer Maximum amount of time (in minutes) for live auto captioning event, including breaks and delays. Event is finished after this time if not finished already.
cancellable Boolean Whether or not the live auto captioning order can be cancelled or updated.
stream_reconnection_wait_time Integer If your stream is disconnected from 3Play, specify how long(in minutes) 3Play should wait before ending your event. After this duration, you will no longer be able to reconnect to this event, and will need to schedule a new event in 3Play to continue captions.

Actions

  • List Unarchived Live Auto Captions in your project

    GET https://api.3playmedia.com/v3/live_auto_captions/

    Parameter Type Description Required Default
    id Integer or Array<Integer> Filter live auto captions by id(s) No no default
    media_file_id Integer or Array<Integer> Filter live auto captions by media file id(s) No no default
    threeplay_transcript_id Integer or Array<Integer> Filter by threeplay transcript id(s) No no default
    public_id Integer or Array<Integer> Filter by public_id(s) No no default
    status Boolean Filter live auto captions by status No no default
    start_before Datetime Filter by live Stream start_time_before No no default
    start_after Datetime Filter by live Stream start_time_after No no default
    created_before Datetime Filter by created_before No no default
    created_after Datetime Filter by created_after No no default
  • Show a specific Live Auto Caption

    GET https://api.3playmedia.com/v3/live_auto_captions/:id

    Parameter Type Description Required Default
    show_embed Boolean Include the example html embed_page attribute for the Live Auto Caption No false
  • Show a specific Live Wordlist

    GET https://api.3playmedia.com/v3/live_auto_captions/:id/wordlist

  • Order Live Auto Captioning

    POST https://api.3playmedia.com/v3/live_auto_captions/order

    Parameter Type Description Required Default
    media_file_id Integer ID of the media file for which you wish to order live auto captioning Yes no default
    stream_url String Stream URL containing the audio to be transcribed No no default
    transcoder_id String 3Play Media ID of a reserved transcoder / stream_target you with to use. No no default
    start_time DateTime Scheduled start time for live auto caption, must be in RFC 3339 format, e.g. '2018-09-01T14:55:00-04:00 Yes no default
    latency Integer Target delay in milliseconds for receiving the live captions at the plugin, in the range 2000 to 15000. Typically, more latency yields more accuracy No 2000
    offensive_words_sensitivity Integer Potentially offensive words are filtered from the live captions. Higher sensitivity means more filtering No 1
    event_wait_time Integer Wait time in minutes for our system to wait after start_time if no audio is found, before event is failed No 30
    event_max_time Integer Maximum time in minutes for the live auto captioning event, before event is finished automatically No 240
    stream_reconnection_wait_time Integer If your stream is disconnected from 3Play, specify how long(in minutes) 3Play should wait before ending your event. After this duration, you will no longer be able to reconnect to this event, and will need to schedule a new event in 3Play to continue captions. No 0
    record_stream Boolean If enabled, the live stream will be saved as the source for the file after the event. This is useful if service upgrades are anticipated, e.g. to Transcription. Leave this off otherwise as it incurs extra processing both during and after the event. This is only available for RTMP streams. No false
    callback String Callback URL for status updates No no default
    wordlist_file File A text file containing a list of up to 75 words or phrases, each on a new line, to aid speech recognition. Files must be provided in a multipart post (e.g. using -F 'wordlist_file=@LOCAL_FILE_PATH' in curl) No no default

  • Note: Some RTMP streams require a 'stream key'. This should be included in the stream_url. For example: 'rtmp://foo.bar.com/fgHJKlmn', where 'fgHJKlmn' is the key.

  • Note: transcoder_id will take precendence over default configured reserved transcoders.

  • Note: If the media_file is configured to use a reserved transcoder, it will overwrite the value passed for stream_url.

  • Note: If the media_file is not configured to use a reserved transcoder and a stream_url is not passed, threeplay will provision a transcoder for you.

  • Note: If a callback url is provided, the payload sent to that URL will be the object representation, in application/x-www-form-urlencoded format.

  • Update Live Auto Captioning

    PUT https://api.3playmedia.com/v3/live_auto_captions/:id

    Parameter Type Description Required Default
    stream_url String Stream containing the audio to be transcribed No no default
    start_time DateTime Scheduled start time for live auto caption, must be in RFC 3339 format, e.g. '2018-09-01T14:55:00-04:00 No no default
    latency Integer Target delay in milliseconds for receiving the live captions at the plugin, in the range 2000 to 15000. No no default
    offensive_words_sensitivity Integer Potentially offensive words are filtered from the live captions No no default
    stream_delay Integer Time in milliseconds by which the playback of the stream is delayed on the client. No no default
    event_wait_time Integer Wait time in minutes for our system to wait after start_time if no audio is found, before event is failed No no default
    event_max_time Integer Maximum time in minutes for the live auto captioning event, before event is finished automatically No no default
    stream_reconnection_wait_time Integer If your stream is disconnected from 3Play, specify how long(in minutes) 3Play should wait before ending your event. After this duration, you will no longer be able to reconnect to this event, and will need to schedule a new event in 3Play to continue captions. No no default
    record_stream Boolean If enabled, the live stream will be saved as the source for the file after the event. This is useful if service upgrades are anticipated, e.g. to Transcription. Leave this off otherwise as it incurs extra processing both during and after the event. This is only available for RTMP streams. No false
    wordlist_file File A text file containing a list of up to 75 words or phrases, each on a new line, to aid speech recognition. Files must be provided in a multipart post (e.g. using -F 'wordlist_file=@LOCAL_FILE_PATH' in curl) No no default
  • Cancel Live Auto Caption

    POST https://api.3playmedia.com/v3/live_auto_captions/:id/cancel

  • Finish Live Auto Caption (e.g. if stream has not ended, but the event has)

    POST https://api.3playmedia.com/v3/live_auto_captions/:id/finish

  • Archive Live Auto Caption (available only if finished or cancelled)

    POST https://api.3playmedia.com/v3/live_auto_captions/:id/archive

  • Unarchive Live Auto Caption (available only if archived)

    POST https://api.3playmedia.com/v3/live_auto_captions/:id/unarchive

  • Get Ordering Help

    GET https://api.3playmedia.com/v3/live_auto_captions/order_help