three_play.v3 package

Submodules

three_play.v3.api module

class three_play.v3.api.ThreePlayApi[source]

Bases: object

Helper class to make requests to the 3Play Media API

API_ENDPOINT = 'https://api.3playmedia.com/v3/'
classmethod archive_media_file(media_file_id: Union[int, List[int]]) → bool[source]

Archive one or more media files.

classmethod callback(transcript_id: int)[source]
classmethod cancel_transcript(transcript_id: int)[source]

Attempt to cancel a 3Play transcript, and return a value indicating whether the cancellation was a success.

classmethod configure(project_api_key)[source]
classmethod create_media_file(video_id: str, video_name: str, language: three_play.v3.models.three_play_media.Language, file_name: Optional[str] = None, integration_id=None, attr1: Optional[str] = None, attr2: Optional[str] = None, attr3: Optional[str] = None, labels: Optional[Dict[str, Any]] = None)[source]

Creates a media file on 3Play, which serves as a reference for the integration service.

Any transcripts can be ordered on media files.

classmethod delete_source(media_file_id: int)[source]
classmethod download_ad_asset(video_id: Optional[str] = None, ad_id: Optional[int] = None, media_format='mp3') → bytes[source]

Download audio description media (description and source mixed)

Returns the downloaded mp3 file as bytes

classmethod get(api, **kwargs)[source]
classmethod get_ad_asset_url(video_id: Optional[str] = None, ad_id: Optional[int] = None, media_format='mp3') → Optional[str][source]

Get a downloadable link for audio description media (description and source mixed)

Raises an ThreePlayError if the latest audio description order is currently in progress.

classmethod get_expiring_edit_url(video_id: Optional[str] = None, transcript_id: Optional[int] = None, expiration_hours: int = 24) → Optional[str][source]

Get an expiring editing link for a transcript_id (or the latest transcript for a video_id).

By default, the link will be valid for up to a day.

classmethod get_formatted_transcript_text(transcript_id: int, start_seconds: Optional[Union[str, int, float]] = None, output_format=<TranscriptFormat.SRT: 7>, clips: Optional[List[str]] = None, log_level=20) → str[source]

Get formatted text (SRT contents by default) for a given transcript.

start_seconds is the number of seconds to cut from the start of the captions. You can also specify milliseconds if you pass it as a string, for example “32.012”.

clips is the portion of the captions to keep, for example if a cut was made in the middle of a video. It can be passed as an array of millisecond pairs, like [‘0,10500’, ‘21060,28140’]

classmethod get_media_file(media_file_id: int)[source]
classmethod get_source(media_file_id: int) → Optional[str][source]

Get the media source for a file.

classmethod get_transcript(transcript_id=None)[source]
classmethod get_transcripts(transcript_id=None, media_file_id=None, media_file_name=None, attr1: Optional[str] = None, attr2: Optional[str] = None, attr3: Optional[str] = None, label: Optional[str] = None, by_default=False, status: Optional[three_play.v3.models.three_play_media.TranscriptStatus] = None, language: Optional[three_play.v3.models.three_play_media.Language] = None, video_id=None, per_page=100, sort_by_created=False, latest_first=False)[source]
classmethod get_translation(media_file_id=None, transcript_id=None)[source]
classmethod import_transcript(media_file_id: int, caption_file_contents: str, language: three_play.v3.models.three_play_media.Language, auto_paragraph=True)[source]

Import a transcript to a media file.

classmethod list_audio_descriptions(transcript_id=None, media_file_id=None, media_file_name=None, attr1: Optional[str] = None, attr2: Optional[str] = None, attr3: Optional[str] = None, status: Optional[three_play.v3.models.three_play_media.TranscriptStatus] = None, language: Optional[three_play.v3.models.three_play_media.Language] = None, video_id=None, per_page=100, sort_by_created=False, created_after: Optional[datetime.datetime] = None)[source]
classmethod list_languages(lang_id: Optional[Union[int, List[int]]] = None, name: Optional[str] = None, name_partial: Optional[str] = None) → List[Dict[str, Any]][source]
classmethod list_media_files(name=None, name_partial=None, video_id=None, attr1: Optional[str] = None, attr2: Optional[str] = None, attr3: Optional[str] = None, per_page=100, sort_by_created=False, latest_first=False)[source]
classmethod list_platform_integrations()[source]
classmethod list_translation_options(source_language: Optional[three_play.v3.models.three_play_media.Language] = None, target_language: Optional[three_play.v3.models.three_play_media.Language] = None, vendor_name=None, vendor_name_partial=None)[source]
classmethod list_turnaround_levels(show_prices=True)[source]
classmethod order_asr(video_id: str, video_name: str, language: three_play.v3.models.three_play_media.Language, file_name: Optional[str] = None, integration_id=None, callback=None, attr1: Optional[str] = None, attr2: Optional[str] = None, attr3: Optional[str] = None, labels: Optional[Dict[str, Any]] = None)[source]

Order Automated Speech Recognition (ASR) for a video.

classmethod order_asr_for_media_file(media_file_id: int, callback=None, read_timeout=2) → bool[source]

Attempt to place an ASR order on a media file, and return a success indicating whether the order was placed successfully.

classmethod order_audio_description_for_media_file(media_file_id: int, turnaround_level: three_play.v3.models.three_play_media.TurnaroundAD = <TurnaroundAD.STANDARD: id=7, hours=120, price=0.0>, extended: bool = False, callback=None, read_timeout=2) → bool[source]

Attempt to place an audio description order on a media file, and return a success indicating whether the order was placed successfully.

If extended is true, order the Extended ADs instead. Note that some platforms (such as Wistia) currently only support Standard ADs.

classmethod order_transcription(video_id: str, video_name: str, language: three_play.v3.models.three_play_media.Language, turnaround_level: three_play.v3.models.three_play_media.Turnaround = <Turnaround.STANDARD: id=1, hours=96, price=0.0>, callback=None, file_name: Optional[str] = None, integration_id=None, attr1: Optional[str] = None, attr2: Optional[str] = None, attr3: Optional[str] = None, labels: Optional[Dict[str, Any]] = None) -> (<class 'int'>, <class 'bool'>)[source]

Orders a transcription for a video. The video_id is unique to the platform (ex. YouTube or Wistia) tied to the integration for the project.

Returns a two-element tuple of (media_file_id, success) where the success indicates whether an order was successfully placed.

classmethod order_transcription_for_media_file(media_file_id: int, turnaround_level: three_play.v3.models.three_play_media.Turnaround = <Turnaround.STANDARD: id=1, hours=96, price=0.0>, callback=None, read_timeout=2) → bool[source]

Attempt to place a transcript order on a media file, and return a success indicating whether the order was placed successfully.

Read the docs on fn:_order_transcription_service for more information.

classmethod order_translation(media_file_id: int, source_language: three_play.v3.models.three_play_media.Language, target_language: three_play.v3.models.three_play_media.Language, source_transcript_id: Optional[int] = None)[source]
classmethod redeliver_transcript(transcript_id: int, service='wistia') → bool[source]

Redelivers a transcript, e.g. triggers the postback, to an integration (defaults to Wistia) with the captions

Returns a Boolean indicating whether the delivery was a success or not.

classmethod request(method, api, log_level=20, **kwargs)[source]
classmethod set_source_url(media_file_id: int, source_url: str)[source]

three_play.v3.helper module

Utility functions for interacting with the 3Play API.

class three_play.v3.helper.ThreePlayHelper[source]

Bases: object

Helper class for interacting with 3Play API, which further simplifies any calls. This assumes that ThreePlayApi has been configured as needed with the API token.

static as_turnaround(turnaround_name: str, default: Optional[Union[three_play.v3.models.three_play_media.Turnaround, three_play.v3.models.three_play_media.TurnaroundAD]] = None, cls: Type[Union[three_play.v3.models.three_play_media.Turnaround, three_play.v3.models.three_play_media.TurnaroundAD]] = <enum 'Turnaround'>)[source]

Attempt to parse a string as a Turnaround or TurnaroundAD.

If turnaround_name is not provided, return the default value. Otherwise if turnaround_name is invalid, an ThreePlayError is raised.

static cancel_transcripts(transcripts: Optional[List[Dict]] = None, video_id=None)[source]

Attempt to cancel any in progress or pending transcript orders for a given video, or given a list of transcripts for a video.

static cut_transcript_in_middle(transcript_id: int, first_end: str, second_start: str, second_offset_ms: int = 0, second_end: str = '99:99:99,999') → str[source]

Get the edited transcript for a transcript_id from 3Play after making a single cut in the middle. The dialogue between first_end and second_start (non-inclusive of the latter) won’t show up in the transcript returned.

This method is needed partly because the clips[] argument is not handled as expected on the 3Play side, e.g. even without second_offset_ms added we still seem to get duplicate dialogue for first_end.

static get_active_transcript_list(video_id) → List[three_play.v3.models.three_play_media.Transcript][source]

Returns the most recent transcripts (which includes the original transcript, and any translations in the case of videos in another language) for the video from 3Play. Returns a list of Transcript objects.

These transcripts are also the ones we would expect to show up as captions on the integration service.

Raises an ThreePlayError if no transcripts are found, or a source language is invalid.

static get_active_transcripts(video_id) → Dict[int, three_play.v3.models.three_play_media.Language][source]

Returns the most recent transcripts (which includes the original transcript, and any translations in the case of videos in another language) for the video from 3Play. Returns a dictionary mapping each Transcript Id to Language.

These transcripts are also the ones we would expect to show up as captions on the integration service.

Raises an ThreePlayError if no transcripts are found, or a source language is invalid.

static get_both_transcript_text(transcript_id: int, start_seconds: Union[str, int, float]) → Tuple[str, str][source]

Retrieve the original transcript text and the trimmed transcript text (after adding the offset start_seconds to the text)

Parameters

  • transcript_id – ID of the 3Play transcript to retrieve the formatted text (in SRT format) for

  • start_seconds – Start offset to specify to trim the transcript

Returns

A tuple of (original_text, trimmed_text)

classmethod get_default_transcripts(video_id, status: Optional[three_play.v3.models.three_play_media.TranscriptStatus] = None, latest_first=False) → List[Dict][source]

Get default transcripts for a video

static get_latest_media_file(video_id: str) → three_play.v3.models.three_play_media.MediaFile[source]

Get the latest media file for a video.

static get_transcript_language(video_id, transcripts=None) → three_play.v3.models.three_play_media.Language[source]

When ‘source_language’ is not passed in the request, get the primary language for a video spoken in an other language from the existing 3Play transcript.

Raises an ThreePlayError if no record for a transcript exists on 3Play.

static get_transcripts(video_id, status: Optional[three_play.v3.models.three_play_media.TranscriptStatus] = None, by_default=False, latest_first=False) → List[Dict][source]

Get all transcripts for a given video.

Module contents

class three_play.v3.ThreePlayApi[source]

Bases: object

Helper class to make requests to the 3Play Media API

API_ENDPOINT = 'https://api.3playmedia.com/v3/'
classmethod archive_media_file(media_file_id: Union[int, List[int]]) → bool[source]

Archive one or more media files.

classmethod callback(transcript_id: int)[source]
classmethod cancel_transcript(transcript_id: int)[source]

Attempt to cancel a 3Play transcript, and return a value indicating whether the cancellation was a success.

classmethod configure(project_api_key)[source]
classmethod create_media_file(video_id: str, video_name: str, language: three_play.v3.models.three_play_media.Language, file_name: Optional[str] = None, integration_id=None, attr1: Optional[str] = None, attr2: Optional[str] = None, attr3: Optional[str] = None, labels: Optional[Dict[str, Any]] = None)[source]

Creates a media file on 3Play, which serves as a reference for the integration service.

Any transcripts can be ordered on media files.

classmethod delete_source(media_file_id: int)[source]
classmethod download_ad_asset(video_id: Optional[str] = None, ad_id: Optional[int] = None, media_format='mp3') → bytes[source]

Download audio description media (description and source mixed)

Returns the downloaded mp3 file as bytes

classmethod get(api, **kwargs)[source]
classmethod get_ad_asset_url(video_id: Optional[str] = None, ad_id: Optional[int] = None, media_format='mp3') → Optional[str][source]

Get a downloadable link for audio description media (description and source mixed)

Raises an ThreePlayError if the latest audio description order is currently in progress.

classmethod get_expiring_edit_url(video_id: Optional[str] = None, transcript_id: Optional[int] = None, expiration_hours: int = 24) → Optional[str][source]

Get an expiring editing link for a transcript_id (or the latest transcript for a video_id).

By default, the link will be valid for up to a day.

classmethod get_formatted_transcript_text(transcript_id: int, start_seconds: Optional[Union[str, int, float]] = None, output_format=<TranscriptFormat.SRT: 7>, clips: Optional[List[str]] = None, log_level=20) → str[source]

Get formatted text (SRT contents by default) for a given transcript.

start_seconds is the number of seconds to cut from the start of the captions. You can also specify milliseconds if you pass it as a string, for example “32.012”.

clips is the portion of the captions to keep, for example if a cut was made in the middle of a video. It can be passed as an array of millisecond pairs, like [‘0,10500’, ‘21060,28140’]

classmethod get_media_file(media_file_id: int)[source]
classmethod get_source(media_file_id: int) → Optional[str][source]

Get the media source for a file.

classmethod get_transcript(transcript_id=None)[source]
classmethod get_transcripts(transcript_id=None, media_file_id=None, media_file_name=None, attr1: Optional[str] = None, attr2: Optional[str] = None, attr3: Optional[str] = None, label: Optional[str] = None, by_default=False, status: Optional[three_play.v3.models.three_play_media.TranscriptStatus] = None, language: Optional[three_play.v3.models.three_play_media.Language] = None, video_id=None, per_page=100, sort_by_created=False, latest_first=False)[source]
classmethod get_translation(media_file_id=None, transcript_id=None)[source]
classmethod import_transcript(media_file_id: int, caption_file_contents: str, language: three_play.v3.models.three_play_media.Language, auto_paragraph=True)[source]

Import a transcript to a media file.

classmethod list_audio_descriptions(transcript_id=None, media_file_id=None, media_file_name=None, attr1: Optional[str] = None, attr2: Optional[str] = None, attr3: Optional[str] = None, status: Optional[three_play.v3.models.three_play_media.TranscriptStatus] = None, language: Optional[three_play.v3.models.three_play_media.Language] = None, video_id=None, per_page=100, sort_by_created=False, created_after: Optional[datetime.datetime] = None)[source]
classmethod list_languages(lang_id: Optional[Union[int, List[int]]] = None, name: Optional[str] = None, name_partial: Optional[str] = None) → List[Dict[str, Any]][source]
classmethod list_media_files(name=None, name_partial=None, video_id=None, attr1: Optional[str] = None, attr2: Optional[str] = None, attr3: Optional[str] = None, per_page=100, sort_by_created=False, latest_first=False)[source]
classmethod list_platform_integrations()[source]
classmethod list_translation_options(source_language: Optional[three_play.v3.models.three_play_media.Language] = None, target_language: Optional[three_play.v3.models.three_play_media.Language] = None, vendor_name=None, vendor_name_partial=None)[source]
classmethod list_turnaround_levels(show_prices=True)[source]
classmethod order_asr(video_id: str, video_name: str, language: three_play.v3.models.three_play_media.Language, file_name: Optional[str] = None, integration_id=None, callback=None, attr1: Optional[str] = None, attr2: Optional[str] = None, attr3: Optional[str] = None, labels: Optional[Dict[str, Any]] = None)[source]

Order Automated Speech Recognition (ASR) for a video.

classmethod order_asr_for_media_file(media_file_id: int, callback=None, read_timeout=2) → bool[source]

Attempt to place an ASR order on a media file, and return a success indicating whether the order was placed successfully.

classmethod order_audio_description_for_media_file(media_file_id: int, turnaround_level: three_play.v3.models.three_play_media.TurnaroundAD = <TurnaroundAD.STANDARD: id=7, hours=120, price=0.0>, extended: bool = False, callback=None, read_timeout=2) → bool[source]

Attempt to place an audio description order on a media file, and return a success indicating whether the order was placed successfully.

If extended is true, order the Extended ADs instead. Note that some platforms (such as Wistia) currently only support Standard ADs.

classmethod order_transcription(video_id: str, video_name: str, language: three_play.v3.models.three_play_media.Language, turnaround_level: three_play.v3.models.three_play_media.Turnaround = <Turnaround.STANDARD: id=1, hours=96, price=0.0>, callback=None, file_name: Optional[str] = None, integration_id=None, attr1: Optional[str] = None, attr2: Optional[str] = None, attr3: Optional[str] = None, labels: Optional[Dict[str, Any]] = None) -> (<class 'int'>, <class 'bool'>)[source]

Orders a transcription for a video. The video_id is unique to the platform (ex. YouTube or Wistia) tied to the integration for the project.

Returns a two-element tuple of (media_file_id, success) where the success indicates whether an order was successfully placed.

classmethod order_transcription_for_media_file(media_file_id: int, turnaround_level: three_play.v3.models.three_play_media.Turnaround = <Turnaround.STANDARD: id=1, hours=96, price=0.0>, callback=None, read_timeout=2) → bool[source]

Attempt to place a transcript order on a media file, and return a success indicating whether the order was placed successfully.

Read the docs on fn:_order_transcription_service for more information.

classmethod order_translation(media_file_id: int, source_language: three_play.v3.models.three_play_media.Language, target_language: three_play.v3.models.three_play_media.Language, source_transcript_id: Optional[int] = None)[source]
classmethod redeliver_transcript(transcript_id: int, service='wistia') → bool[source]

Redelivers a transcript, e.g. triggers the postback, to an integration (defaults to Wistia) with the captions

Returns a Boolean indicating whether the delivery was a success or not.

classmethod request(method, api, log_level=20, **kwargs)[source]
classmethod set_source_url(media_file_id: int, source_url: str)[source]
class three_play.v3.ThreePlayHelper[source]

Bases: object

Helper class for interacting with 3Play API, which further simplifies any calls. This assumes that ThreePlayApi has been configured as needed with the API token.

static as_turnaround(turnaround_name: str, default: Optional[Union[three_play.v3.models.three_play_media.Turnaround, three_play.v3.models.three_play_media.TurnaroundAD]] = None, cls: Type[Union[three_play.v3.models.three_play_media.Turnaround, three_play.v3.models.three_play_media.TurnaroundAD]] = <enum 'Turnaround'>)[source]

Attempt to parse a string as a Turnaround or TurnaroundAD.

If turnaround_name is not provided, return the default value. Otherwise if turnaround_name is invalid, an ThreePlayError is raised.

static cancel_transcripts(transcripts: Optional[List[Dict]] = None, video_id=None)[source]

Attempt to cancel any in progress or pending transcript orders for a given video, or given a list of transcripts for a video.

static cut_transcript_in_middle(transcript_id: int, first_end: str, second_start: str, second_offset_ms: int = 0, second_end: str = '99:99:99,999') → str[source]

Get the edited transcript for a transcript_id from 3Play after making a single cut in the middle. The dialogue between first_end and second_start (non-inclusive of the latter) won’t show up in the transcript returned.

This method is needed partly because the clips[] argument is not handled as expected on the 3Play side, e.g. even without second_offset_ms added we still seem to get duplicate dialogue for first_end.

static get_active_transcript_list(video_id) → List[three_play.v3.models.three_play_media.Transcript][source]

Returns the most recent transcripts (which includes the original transcript, and any translations in the case of videos in another language) for the video from 3Play. Returns a list of Transcript objects.

These transcripts are also the ones we would expect to show up as captions on the integration service.

Raises an ThreePlayError if no transcripts are found, or a source language is invalid.

static get_active_transcripts(video_id) → Dict[int, three_play.v3.models.three_play_media.Language][source]

Returns the most recent transcripts (which includes the original transcript, and any translations in the case of videos in another language) for the video from 3Play. Returns a dictionary mapping each Transcript Id to Language.

These transcripts are also the ones we would expect to show up as captions on the integration service.

Raises an ThreePlayError if no transcripts are found, or a source language is invalid.

static get_both_transcript_text(transcript_id: int, start_seconds: Union[str, int, float]) → Tuple[str, str][source]

Retrieve the original transcript text and the trimmed transcript text (after adding the offset start_seconds to the text)

Parameters

  • transcript_id – ID of the 3Play transcript to retrieve the formatted text (in SRT format) for

  • start_seconds – Start offset to specify to trim the transcript

Returns

A tuple of (original_text, trimmed_text)

classmethod get_default_transcripts(video_id, status: Optional[three_play.v3.models.three_play_media.TranscriptStatus] = None, latest_first=False) → List[Dict][source]

Get default transcripts for a video

static get_latest_media_file(video_id: str) → three_play.v3.models.three_play_media.MediaFile[source]

Get the latest media file for a video.

static get_transcript_language(video_id, transcripts=None) → three_play.v3.models.three_play_media.Language[source]

When ‘source_language’ is not passed in the request, get the primary language for a video spoken in an other language from the existing 3Play transcript.

Raises an ThreePlayError if no record for a transcript exists on 3Play.

static get_transcripts(video_id, status: Optional[three_play.v3.models.three_play_media.TranscriptStatus] = None, by_default=False, latest_first=False) → List[Dict][source]

Get all transcripts for a given video.