podcast-transcript-convert

Convert podcast transcripts from HTML, SRT, WebVtt, Podlove etc into PodcastIndex JSON.

Requires Python 3.13 or later.

Installation

It is recommended to use pipx or uv to install and run the CLI tool. If you wish to use the library, you can install with pip instead.

brew install pipx
pipx install podcast-transcript-convert
# or: uv tool install podcast-transcript-convert

If you've already installed the package and wish to upgrade:

pipx upgrade podcast-transcript-convert

Usage

Run the conversion app on your transcripts directory.

transcript2json transcripts/ converted/

You can then inspect the output JSON files in the converted/ directory. The directory structure of transcripts/ is mirrored in converted/ so that files with the same name do not collide.

You can also convert a single file:

transcript2json "episode.srt" converted/
# or specify the output file name
transcript2json "episode.srt" episode.json

Or read transcript paths and episode metadata from an overcast-to-sqlite database (episode and feed metadata is embedded in the output JSON):

transcript2json overcast.db converted/

Options

Files that fail to convert are logged and skipped — a single malformed transcript will not abort a bulk run. The exit code is 0 on success and 1 when nothing could be converted.

Library Usage

from podcast_transcript_convert.convert import bulk_convert

summary = bulk_convert("transcripts_dir/", "converted_dir/")
print(f"{len(summary.converted)} converted, {len(summary.failed)} failed")

bulk_convert accepts optional ignore (list of filenames to skip), overwrite, and dry_run arguments and returns a ConversionSummary with converted, skipped, failed, and unknown file lists.

To convert a single file of any supported type:

from podcast_transcript_convert.convert import convert_file

convert_file("episode.srt", "episode.json")

Individual file type converters are in the converters package. You can use them directly if you know the file type.

You can use file_typing.identify_file_type(file) to determine the file type of a transcript file, or file_typing.identify_file_types(files) to group a collection of paths by detected type.

Development

Pull requests are very welcome! For major changes, please open an issue first to discuss what you would like to change.

This project uses uv for dependency management, building, and publishing.

git clone git@github.com:hbmartin/podcast-transcript-convert.git
cd podcast-transcript-convert
uv sync
uv run pytest
# Replace with the actual path to your transcript files
uv run transcript2json ~/Downloads/overcast-to-sqlite/archive/transcripts converted/

Code Quality

This project is linted with ruff, uses Black code formatting, and is type checked with ty and pyrefly.

uv run ruff check .
uv run ty check podcast_transcript_convert
uv run pyrefly check

Authors

• Harold Martin - harold.martin at gmail
• Icon courtesy of Vecteezy.com