3Play Media: Docs

Live Professional Captioning

Live Professional Captioning is currently in Beta, please follow the instructions in this support document for access to this service

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

Cancellation of a professionally captioned event that has been matched to a captioner within 24 hours of the Event Start will result in full charges for the event.

Please also note that the stream URL for live professional 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 professional caption
media_file_id Integer ID of the 3Play Media file that your live professional caption belongs to
threeplay_transcript_id Integer ID of the 3Play Transcript that your live professional caption produces, needed for downloading
language_id Integer Language ID of the media file
embed_code String iFrame embed code for the live professional caption plugin
js_embed_code String Javascript embed code for the live professional 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 professional caption, which can be used to modify an existing plugin
status String Status of live professional 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 professional 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 professional captioning event, including breaks and delays. Event is finished after this time if not finished already.
cancellable Boolean Whether or not the live professional 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.
meeting_location String The URL or phone number to allow the captioner to access your event audio (for example, a link to join a WebEx meeting.)
captioner_join_time DateTime Scheduled time for a 3Play Professional Captioner to joining your event

Actions

  • List Unarchived Live Professional Captions in your project

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

    Parameter Type Description Required Default
    id Integer or Array<Integer> Filter live professional captions by id(s) No no default
    media_file_id Integer or Array<Integer> Filter live professional 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 professional 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 Professional Caption

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

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

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

  • Order Live Professional Captioning

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

    Parameter Type Description Required Default
    media_file_id Integer ID of the media file for which you wish to order live professional 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 professional 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. For streamless events this has no effect. No 30
    event_max_time Integer Maximum time in minutes for the live professional captioning event, before event is finished automatically. For streamless events this has no effect. 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. For streamless events this has no effect. 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
    live_event_type String An event type chosen from one of the following types [Lecture/Class, Conference Calls/Meetings, Training Sessions, Webinar/Webcasts, Interviews, Concerts/Musical Performances, Sporting Events, Focus Groups] No no default
    fallback_to_automatic_captions Boolean What should 3Play do if your event exceeds the estimated duration? The default is to continue with professional captions. Note that the price of professional captions increases to $3.00 per minute after the estimated duration. No false
    event_description string Provide context around your event by adding general information around speakers, event purpose, and other information. No no default
    speaker_names Array Add a list of names of people who may be speaking during the event to more accurately caption speaker labels. No no default
    estimated_duration Integer Estimate of the duration of live event in milliseconds. Yes no default
    meeting_location String The URL or phone number to allow the captioner to access your event audio (for example, a link to join a WebEx meeting) No no default
    additional_instructions String Any additional information that the captioner needs to know to access the event audio. This could include a secondary method for accessing the event. No no default
    captioner_join_time DateTime The time at which the captioner will be able to access the event audio. No no default
    has_live_stream Boolean The indicator for whether or not an event has an automatically accessible source stream. No true
    contact_name String The name of the person managing captions for your live captioning event. 3Play may contact this person for the purposes of providing event support. No no default
    contact_email String The email of the person managing captions for your live captioning event. 3Play may contact this person for the purposes of providing event support. No no default
    contact_phone_number String The phone number of the person managing captions for your live captioning event. 3Play may contact this person for the purposes of providing event support. 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.

  • Note: If 'has_live_stream' is false, a 3Play professional captioner must have direct access to your event (e.g. from a meeting platform URL provided in the 'additional_instructions' field). Events that do not have a source stream can only be captioned professionally; automated captioning fallback is unavailable

  • Update Live Professional Captioning

    PUT https://api.3playmedia.com/v3/live_professional_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 professional 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. For streamless events this has no effect. No no default
    event_max_time Integer Maximum time in minutes for the live professional captioning event, before event is finished automatically. For streamless events this has no effect. 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. For streamless events this has no effect. 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 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
    live_event_type String An event type chosen from one of the following types [Lecture/Class, Conference Calls/Meetings, Training Sessions, Webinar/Webcasts, Interviews, Concerts/Musical Performances, Sporting Events, Focus Groups] No no default
    fallback_to_automatic_captions Boolean What should 3Play do if your event exceeds the estimated duration? The default is to continue with professional captions. Note that the price of professional captions increases to $3.00 per minute after the estimated duration. No no default
    event_description string Provide context around your event by adding general information around speakers, event purpose, and other information. No no default
    speaker_names Array Add a list of names of people who may be speaking during the event to more accurately caption speaker labels. No no default
    meeting_location String The URL or phone number to allow the captioner to access your event audio (for example, a link to join a WebEx meeting) No no default
    additional_instructions String Any additional information that the captioner needs to know to access the event audio. This could include a secondary method for accessing the event. No no default
    captioner_join_time DateTime The time at which the captioner will be able to access the event audio. No no default
    contact_name String The name of the person managing captions for your live captioning event. 3Play may contact this person for the purposes of providing event support. No no default
    contact_email String The email of the person managing captions for your live captioning event. 3Play may contact this person for the purposes of providing event support. No no default
    contact_phone_number String The phone number of the person managing captions for your live captioning event. 3Play may contact this person for the purposes of providing event support. No no default
  • Cancel Live Professional Caption

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

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

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

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

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

  • Unarchive Live Professional Caption (available only if archived)

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

  • Get Ordering Help

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