pressurecooker

A library of various media processing functions and utilities

Setting up your environment

• Install ffmpeg if you don't have it already.

• Install GhostScript if you don't have it already.

• Install poppler-utils if you don't have it already

TODO

• pressurecooker.youtube v2 spec: see https://github.com/learningequality/pressurecooker/issues/32
• To handle ExtractorError as permanent failure (do not try to download repeatedly)
• Add to Youtube video API (support for start time) https://www.youtube.com/watch?v=GOJUNJ1o394&t=52 End time complicated https://www.youtube.com/embed/WA8sLsM3McU?start=15&end=20 but still possible https://stackoverflow.com/questions/4661905/how-to-customize-an-end-time-for-a-youtube-video See https://developers.google.com/youtube/player_parameters

Converting caption files

The pressurecooker library contains utilities for converting caption files from a few various formats into the preferred VTT format. The currently supported formats include:

• DFXP
• SAMI
• SCC
• SRT
• TTML
• WebVTT or just VTT

Within pressurecooker, the term "captions" and "subtitles" are used interchangeably. All of the classes and functions handling conversion use the "subtitles" term.

Language codes

The DFXP, SAMI, and TTML formats can encapsulate caption contents for multiple languages within one file. The SCC, SRT, and VTT formats are generally limited to a single language that isn't defined in the file (the VTT may be an exception to this rule, but our converters do not detect its language). Therefore when converting these files we cannot know what language we are working with and must instead use the constant LANGUAGE_CODE_UNKNOWN to extract the converted subtitles.

Note also that language codes used within the subtitle files might differ from the LE internal language codes defined in le-utils.

Creating a converter from a file

To create a subtitle converter from a local file path, use these commands:

frompressurecooker.subtitlesimportbuild_subtitle_converter_from_fileconverter=build_subtitle_converter_from_file('/path/to/file.srt')

Creating a converter from a string

If you already have the captions loaded into a string variable, you can create the converter like so:

frompressurecooker.subtitlesimportbuild_subtitle_convertercaptions_str=''# In this example, `captions_str` holds the caption contentsconverter=build_subtitle_converter(captions_str)

Converting captions

For the SCC, SRT, and VTT subtitles format that do not contain language code info, you must refer to the language as the constant LANGUAGE_CODE_UNKNOWN at the time of extracting the converted subtitles:

frompressurecooker.subtitlesimportbuild_subtitle_converter_from_filefrompressurecooker.subtitlesimportLANGUAGE_CODE_UNKNOWNconverter=build_subtitle_converter_from_file('/path/to/file.srt')
# Option A: Obtain the contents of the converted VTT file as a stringoutput_str=converter.convert(LANGUAGE_CODE_UNKNOWN)
# Option B: Write the converted subtitles to a local pathconverter.write("/path/to/file.vtt", LANGUAGE_CODE_UNKNOWN)

The LANGUAGE_CODE_UNKNOWN constant is the internal representation pycaption uses to denote subtitles in an unknown language code. This will be the default and only language code for SCC, SRT, and VTT subtitle converters.

If you are unsure of the format, but you know the language of the file, it is safer to conditionally replace the LANGUAGE_CODE_UNKNOWN with that language:

frompressurecooker.subtitlesimportbuild_subtitle_converter_from_filefrompressurecooker.subtitlesimportLANGUAGE_CODE_UNKNOWNconverter=build_subtitle_converter_from_file('/path/to/file')
# Replace unknown language code if presentifconverter.has_language(LANGUAGE_CODE_UNKNOWN):
converter.replace_unknown_language('en')
assertconverter.has_language('en'), 'Must have English after replace'output_str=converter.convert('en')

An example showing how to handle the subtitle formats like DFXP, SAMI, and TTML, which have multiple languages is shown below:

frompressurecooker.subtitlesimportbuild_subtitle_converter_from_filefrompressurecooker.subtitlesimportLANGUAGE_CODE_UNKNOWN, InvalidSubtitleLanguageErrorconverter=build_subtitle_converter_from_file('/path/to/file')
forlang_codeinconverter.get_language_codes():
# `some_logic` would be your decisions on whether to use this languageifsome_logic(lang_code):
converter.write("/path/to/file-{}.vtt".format(lang_code), lang_code)
eliflang_code==LANGUAGE_CODE_UNKNOWN:
raiseInvalidSubtitleLanguageError('Unexpected unknown language')