Skip to main content

Transcribes audio files to .srt

Project description


Transcribes an audio file to .srt subtitle format using word timings from Google's Speech-to-Text API.



pip install substream

Cloud setup:

  • Create a new service account for a new project dedicated to your recognition job. It must have the following permissions:

    • Cloud Speech Service Agent
    • Storage Admin OR
    • Storage Object Viewer if supplying a gs:// URI to the script.

    You can set the location to the .json credentials file you downloaded in the current environment like:

    export GOOGLE_APPLICATION_CREDENTIALS=/path/to/cloud_credentials.json

    (OR) you can set it just before the substream command like:

    GOOGLE_APPLICATION_CREDENTIALS=/path/to/cloud_credentials.json substream ...

    On run, a temporary bucket will be created, the file uploaded, and on completion or error, a context manager ensures bucket deletion.

    Please be careful with these credentials as cloud resources can be expensive, so make to store them securely if you do store them at all, and make sure all project buckets are deleted manually even if the app reports they have been successfully deleted.

Full Usage:

usage: substream [-h] -i INPUT -o SRT_FILENAME [--language CODE] [-v]

Transcribes an audio file or .jsonl dump to .srt using the Google Cloud
Speech-to-Text API

optional arguments:
  -h, --help            show this help message and exit
  -i INPUT, --input INPUT
                        mono audio file (flac, opus, 16 bit pcm) (or) gs://
                        uri to audio file (or) intermediate .jsonl dump
                        (default: None)
                        .srt filename (default: None)
  --language CODE
                        (default: en-US)
  -v, --verbose         extra logging (default: False)

Sample Usage with a local file:

substream -v -i test.flac -o --language en-US

Sample usage with a URI:

substream -v -i gs://my-bucket/test.flac -o


pip uninstall substream


  • Why the long-running API rather than the streaming API?

    The long running API is more accurate.

  • What is the .jsonl file?

    Each stripped line in the file is a string containing a json representation of a word with it's start and end timings. Later versions of this program may accept the .jsonl file to format the sentences in a better way without having to re-run the audio transcription.

  • Known Issues:

    • 'walls of text' caused by people speaking without interruption. Some subtitles may have to be manually split using a .srt editor.

    • Speaker identification is currently broken in the long running api for long files, so splitting on this is curently disabled. (this exacerbates the above point)

    • Progress report is unimplemented by the long running API currently.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for substream, version 0.1.1
Filename, size File type Python version Upload date Hashes
Filename, size substream-0.1.1.tar.gz (8.5 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page