# LeGen
LeGen is a fast, AI-powered subtitle studio that runs right on your machine. It taps into Whisper and WhisperX to transcribe speech, translates the results into the language you need, then exports polished `.srt`/`.txt` files, muxes them into MP4 containers, or even burns them straight into the video. LeGen also speaks fluent `yt-dlp`, pulling remote videos or playlists and embedding every subtitle track it can find before the pipeline kicks in.
This is very useful for making it available in another language, or even just subtitling any video that belongs to you or that you have the proper authorization to do so, be it a film, lecture, course, presentation, interview, etc.
## Run on Colab
LeGen works on Google Colab, using their computing power to do the work. Aceess the link to [run on Google Colab](https://colab.research.google.com/github/matheusbach/legen/blob/main/legen.ipynb)
<a href='https://colab.research.google.com/github/matheusbach/legen/blob/main/legen.ipynb' style='padding-left: 0.5rem;'><img src='https://colab.research.google.com/assets/colab-badge.svg' alt='Google Colab'></a>
## Install
### From PyPI
Install the published package directly from [PyPI](https://pypi.org/project/legen/):
```sh
pip install legen
```
The `legen` console script will be added to your PATH and mirrors all CLI options documented below.
### From source
Install FFMpeg from [FFMPeg Oficial Site](https://ffmpeg.org/download.html) or from your linux package manager. _If using windows, prefer gyan_dev release full `choco install ffmpeg-full`_
Install [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
Install [Python](https://www.python.org/downloads/) Recomended version: 3.12.x. _If using windows, select "Add to PATH" option when installing_
Clone LeGen using git
```sh
git clone https://github.com/matheusbach/legen.git
cd legen
```
Install requirements using pip. Is recommended to create a virtual environment (venv) as a good practice
```sh
pip3 install -r requirements.txt --upgrade
```
Ensure the `yt-dlp` command is available in your shell so LeGen can fetch remote videos. The provided requirements install `yt-dlp` for convenience, and LeGen will use it to embed all subtitle tracks it can find for each item into the MP4 container.
### GPU compatibility
If having troubles with GPU compatibility, get [PyTorch](https://pytorch.org/get-started/locally/) for your GPU.
_And done. Now you can use LeGen_
### Update
For dry-run update, use in legen folder:
```sh
git fetch && git reset --hard origin/main && git pull
pip3 install -r requirements.txt --upgrade --force-reinstall
```
## Run locally:
To use LeGen, run the following command:
The minimum comand line is:
```sh
python3 legen.py -i [input_path]
```
Users could for example also translate generated subtitles for other language like portuguese (pt) adding `--translate pt` to the command line
Full options list are described bellow:
- `-i`, `--input_path`: Specifies the path to the media files or a direct video/playlist URL. The CLI will download URLs with `yt-dlp` before processing. Example: `LeGen -i /path/to/media/files` or `LeGen -i https://www.youtube.com/watch?v=…`.
- `--norm`: Normalizes folder times and runs vidqa on the input path before starting to process files. Useful for synchronizing timestamps across multiple media files.
- `-ts:e`, `--transcription_engine`: Specifies the transcription engine to use. Possible values are "whisperx" and "whisper". Default is "whisperx".
- `-ts:m`, `--transcription_model`: Specifies the path or name of the Whisper transcription model. A larger model will consume more resources and be slower, but with better transcription quality. Possible values: tiny, base, small, medium, large, large-v3, turbo, large-v3-turbo (default)...
- `-ts:d`, `--transcription_device`: Specifies the device to run the transcription through Whisper. Possible values: auto (default), cpu, cuda.
- `-ts:c`, `--transcription_compute_type`: Specifies the quantization for the neural network. Possible values: auto (default), int8, int8_float32, int8_float16, int8_bfloat16, int16, float16, bfloat16, float32.
- `-ts:b`, `--transcription_batch`: Specifies the number of simultaneous segments being transcribed. Higher values will speed up processing. If you have low RAM/VRAM, long duration media files or have buggy subtitles, reduce this value to avoid issues. Only works using transcription_engine whisperx. Default is 4.
- `--translate`: Translates subtitles to a language code if they are not the same as the original. The language code should be specified after the equals sign. For example, `LeGen --translate=fr` would translate the subtitles to French.
- `--input_lang`: Indicates (forces) the language of the voice in the input media. Default is "auto".
- `-c:v`, `--codec_video`: Specifies the target video codec. Can be used to set acceleration via GPU or another video API [codec_api], if supported (ffmpeg -encoders). Examples include h264, libx264, h264_vaapi, h264_nvenc, hevc, libx265 hevc_vaapi, hevc_nvenc, hevc_cuvid, hevc_qsv, hevc_amf. Default is h264.
- `-c:a`, `--codec_audio`: Specifies the target audio codec. Default is aac. Examples include aac, libopus, mp3, vorbis.
- `-o:s`, `--output_softsubs`: Specifies the path to the folder or output file for the video files with embedded softsub (embedded in the mp4 container and .srt files). Default is "softsubs_" followed by the input path.
- `-o:h`, `--output_hardsubs`: Specifies the output folder path for video files with burned-in captions and embedded in the mp4 container. Default is "hardsubs_" followed by the input path.
- `-o:d`, `--output_downloads`: Overrides the folder used to store media downloaded from URL inputs. Default is `./downloads` when `-i` receives a URL.
- `--overwrite`: Overwrites existing files in output directories. By default, this option is false.
- `-dl:rs`, `--download_remote_subs`: When supplied alongside a URL input, instructs `yt-dlp` to download and embed every subtitle track it can find into the downloaded MP4. By default, remote subtitles are not fetched.
- `--subtitle_formats`: Specifies which subtitle formats should be exported. Separate multiple values with comma or space. Supported formats: `srt`, `txt`. Example: `--subtitle_formats srt,txt`.
- `--disable_srt`: Disables .srt file generation and doesn't insert subtitles in the mp4 container of output_softsubs. Equivalent to removing `srt` from `--subtitle_formats`. By default, this option is false.
- `--disable_softsubs`: Doesn't insert subtitles in the mp4 container of output_softsubs. This option continues generating .srt files. By default, this option is false.
- `--disable_hardsubs`: Disables subtitle burn in output_hardsubs. By default, this option is false.
- `--copy_files`: Copies other (non-video) files present in the input directory to output directories. Only generates the subtitles and videos. By default, this option is false.
- `--translate_engine`: Selects the translation engine. Possible values: `google` (default), `gemini`.
- `--gemini_api_key`: Gemini API key used for translation when `--translate_engine gemini`. Repeat the flag or separate keys with commas/line breaks to supply multiple keys (useful for rotating free-tier quotas). Get your keys at https://aistudio.google.com/apikey
Each of these options provides control over various aspects of the video processing workflow. Make sure to refer to the documentation or help message (`LeGen --help`) for more details on each option[Source 0](https://docs.python.org/3/library/argparse.html)[Source 2](https://realpython.com/command-line-interfaces-python-argparse/).
### Downloading from URLs
When you pass a HTTP(S) URL to `-i`, LeGen will:
- Invoke `yt-dlp` to download the target video, playlist, or batch feed.
- Embed every subtitle track the platform exposes directly into the downloaded media **only when `--download_remote_subs` is provided**.
- Force `mp4` output with the best available video and audio combination.
- Store the media under `./downloads` or the path provided through `--output_downloads`.
- Continue the normal transcription/translation pipeline on the freshly downloaded files with no additional steps from you.
If the value supplied to `-i` is neither a reachable URL nor a valid local file/folder, LeGen will abort with a clear error message so you can correct the input.
## Dependencies
LeGen requires the following **pip** dependencies to be installed:
- deep_translator
- ffmpeg_progress_yield
- openai_whisper
- pysrt
- torch
- tqdm
- whisper
- vidqa
- whisperx-legen-fork (legen flavored fork from m-bain/whisperx)
- gemini-srt-translator
- yt-dlp
This dependencies can be installed and updated with ```pip install -r requirements.txt --upgrade```
LeGen requires the `yt-dlp` CLI on your system to download remote content automatically.
You also need to [install FFmpeg](https://ffmpeg.org/download.html)
## Contributing
Contributions are welcome. Submit your pull request ❤️
## Issues, Doubts
Not being able to use the software, or encountering an error? open an [issue](https://github.com/matheusbach/legen/issues/new)
## Telegram Group
Welcome and don't be a sick. We are brazilian, but you can write in other language if you want. https://t.me/+c0VRonlcd9Q2YTAx
## Video Tutorials
[PT-BR] [SEMI-OUTDATED] [**Tutorial - LeGen no Google Colab**](https://odysee.com/@legen_software:d/legen_no_colab:0)
## Donations
You can donate to project using:
Monero (XMR): ```86HjTCsiaELEoNhH96rTf3ezGMXgKmHjqFrNmca2tesCESdCTZvRvQ9QWQXPGDtmaZhKz4ryHCdZXFzdbmtGahVa5VMLJnx```
LivePix: https://livepix.gg/legendonate
### Donators
- Picasso Neves
- Erasmo de Souza Mora
- viniciuspro
- Igor
- NiNi
- PopularC
## License
This project is licensed under the terms of the [GNU GPLv3](https://choosealicense.com/licenses/gpl-3.0/).
Raw data
{
"_id": null,
"home_page": null,
"name": "legen",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.13,>=3.9",
"maintainer_email": null,
"keywords": "subtitles, whisper, translation, ffmpeg, yt-dlp",
"author": "Matheus Bach",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/09/61/d605683f307d1567c0ec1fa3e2342e15db3c7e6d83c6ffdc68cde7868954/legen-0.19.3.tar.gz",
"platform": null,
"description": "# LeGen\n\n\n\n\nLeGen is a fast, AI-powered subtitle studio that runs right on your machine. It taps into Whisper and WhisperX to transcribe speech, translates the results into the language you need, then exports polished `.srt`/`.txt` files, muxes them into MP4 containers, or even burns them straight into the video. LeGen also speaks fluent `yt-dlp`, pulling remote videos or playlists and embedding every subtitle track it can find before the pipeline kicks in.\n\nThis is very useful for making it available in another language, or even just subtitling any video that belongs to you or that you have the proper authorization to do so, be it a film, lecture, course, presentation, interview, etc.\n\n## Run on Colab\n\nLeGen works on Google Colab, using their computing power to do the work. Aceess the link to [run on Google Colab](https://colab.research.google.com/github/matheusbach/legen/blob/main/legen.ipynb)\n\n <a href='https://colab.research.google.com/github/matheusbach/legen/blob/main/legen.ipynb' style='padding-left: 0.5rem;'><img src='https://colab.research.google.com/assets/colab-badge.svg' alt='Google Colab'></a>\n\n## Install\n\n### From PyPI\n\nInstall the published package directly from [PyPI](https://pypi.org/project/legen/):\n\n```sh\npip install legen\n```\n\nThe `legen` console script will be added to your PATH and mirrors all CLI options documented below.\n\n### From source\n\nInstall FFMpeg from [FFMPeg Oficial Site](https://ffmpeg.org/download.html) or from your linux package manager. _If using windows, prefer gyan_dev release full `choco install ffmpeg-full`_\n\nInstall [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)\n\nInstall [Python](https://www.python.org/downloads/) Recomended version: 3.12.x. _If using windows, select \"Add to PATH\" option when installing_\n\nClone LeGen using git\n```sh\ngit clone https://github.com/matheusbach/legen.git\ncd legen\n```\n\nInstall requirements using pip. Is recommended to create a virtual environment (venv) as a good practice\n```sh\npip3 install -r requirements.txt --upgrade\n```\n\nEnsure the `yt-dlp` command is available in your shell so LeGen can fetch remote videos. The provided requirements install `yt-dlp` for convenience, and LeGen will use it to embed all subtitle tracks it can find for each item into the MP4 container.\n\n### GPU compatibility\n\nIf having troubles with GPU compatibility, get [PyTorch](https://pytorch.org/get-started/locally/) for your GPU.\n\n_And done. Now you can use LeGen_\n\n### Update\n\nFor dry-run update, use in legen folder:\n```sh\ngit fetch && git reset --hard origin/main && git pull\npip3 install -r requirements.txt --upgrade --force-reinstall\n```\n\n## Run locally:\n\nTo use LeGen, run the following command:\n\nThe minimum comand line is:\n\n```sh\npython3 legen.py -i [input_path]\n```\n\nUsers could for example also translate generated subtitles for other language like portuguese (pt) adding `--translate pt` to the command line\n\n\nFull options list are described bellow:\n\n- `-i`, `--input_path`: Specifies the path to the media files or a direct video/playlist URL. The CLI will download URLs with `yt-dlp` before processing. Example: `LeGen -i /path/to/media/files` or `LeGen -i https://www.youtube.com/watch?v=\u2026`.\n\n- `--norm`: Normalizes folder times and runs vidqa on the input path before starting to process files. Useful for synchronizing timestamps across multiple media files.\n\n- `-ts:e`, `--transcription_engine`: Specifies the transcription engine to use. Possible values are \"whisperx\" and \"whisper\". Default is \"whisperx\".\n\n- `-ts:m`, `--transcription_model`: Specifies the path or name of the Whisper transcription model. A larger model will consume more resources and be slower, but with better transcription quality. Possible values: tiny, base, small, medium, large, large-v3, turbo, large-v3-turbo (default)...\n\n- `-ts:d`, `--transcription_device`: Specifies the device to run the transcription through Whisper. Possible values: auto (default), cpu, cuda.\n\n- `-ts:c`, `--transcription_compute_type`: Specifies the quantization for the neural network. Possible values: auto (default), int8, int8_float32, int8_float16, int8_bfloat16, int16, float16, bfloat16, float32.\n\n- `-ts:b`, `--transcription_batch`: Specifies the number of simultaneous segments being transcribed. Higher values will speed up processing. If you have low RAM/VRAM, long duration media files or have buggy subtitles, reduce this value to avoid issues. Only works using transcription_engine whisperx. Default is 4.\n\n- `--translate`: Translates subtitles to a language code if they are not the same as the original. The language code should be specified after the equals sign. For example, `LeGen --translate=fr` would translate the subtitles to French.\n\n- `--input_lang`: Indicates (forces) the language of the voice in the input media. Default is \"auto\".\n\n- `-c:v`, `--codec_video`: Specifies the target video codec. Can be used to set acceleration via GPU or another video API [codec_api], if supported (ffmpeg -encoders). Examples include h264, libx264, h264_vaapi, h264_nvenc, hevc, libx265 hevc_vaapi, hevc_nvenc, hevc_cuvid, hevc_qsv, hevc_amf. Default is h264.\n\n- `-c:a`, `--codec_audio`: Specifies the target audio codec. Default is aac. Examples include aac, libopus, mp3, vorbis.\n\n- `-o:s`, `--output_softsubs`: Specifies the path to the folder or output file for the video files with embedded softsub (embedded in the mp4 container and .srt files). Default is \"softsubs_\" followed by the input path.\n\n- `-o:h`, `--output_hardsubs`: Specifies the output folder path for video files with burned-in captions and embedded in the mp4 container. Default is \"hardsubs_\" followed by the input path.\n\n- `-o:d`, `--output_downloads`: Overrides the folder used to store media downloaded from URL inputs. Default is `./downloads` when `-i` receives a URL.\n\n- `--overwrite`: Overwrites existing files in output directories. By default, this option is false.\n\n- `-dl:rs`, `--download_remote_subs`: When supplied alongside a URL input, instructs `yt-dlp` to download and embed every subtitle track it can find into the downloaded MP4. By default, remote subtitles are not fetched.\n\n- `--subtitle_formats`: Specifies which subtitle formats should be exported. Separate multiple values with comma or space. Supported formats: `srt`, `txt`. Example: `--subtitle_formats srt,txt`.\n\n- `--disable_srt`: Disables .srt file generation and doesn't insert subtitles in the mp4 container of output_softsubs. Equivalent to removing `srt` from `--subtitle_formats`. By default, this option is false.\n\n- `--disable_softsubs`: Doesn't insert subtitles in the mp4 container of output_softsubs. This option continues generating .srt files. By default, this option is false.\n\n- `--disable_hardsubs`: Disables subtitle burn in output_hardsubs. By default, this option is false.\n\n- `--copy_files`: Copies other (non-video) files present in the input directory to output directories. Only generates the subtitles and videos. By default, this option is false.\n\n- `--translate_engine`: Selects the translation engine. Possible values: `google` (default), `gemini`.\n- `--gemini_api_key`: Gemini API key used for translation when `--translate_engine gemini`. Repeat the flag or separate keys with commas/line breaks to supply multiple keys (useful for rotating free-tier quotas). Get your keys at https://aistudio.google.com/apikey\n\nEach of these options provides control over various aspects of the video processing workflow. Make sure to refer to the documentation or help message (`LeGen --help`) for more details on each option[Source 0](https://docs.python.org/3/library/argparse.html)[Source 2](https://realpython.com/command-line-interfaces-python-argparse/).\n\n### Downloading from URLs\n\nWhen you pass a HTTP(S) URL to `-i`, LeGen will:\n\n- Invoke `yt-dlp` to download the target video, playlist, or batch feed.\n- Embed every subtitle track the platform exposes directly into the downloaded media **only when `--download_remote_subs` is provided**.\n- Force `mp4` output with the best available video and audio combination.\n- Store the media under `./downloads` or the path provided through `--output_downloads`.\n- Continue the normal transcription/translation pipeline on the freshly downloaded files with no additional steps from you.\n\nIf the value supplied to `-i` is neither a reachable URL nor a valid local file/folder, LeGen will abort with a clear error message so you can correct the input.\n\n## Dependencies\n\nLeGen requires the following **pip** dependencies to be installed:\n- deep_translator\n- ffmpeg_progress_yield\n- openai_whisper\n- pysrt\n- torch\n- tqdm\n- whisper\n- vidqa\n- whisperx-legen-fork (legen flavored fork from m-bain/whisperx)\n- gemini-srt-translator\n- yt-dlp\n\nThis dependencies can be installed and updated with ```pip install -r requirements.txt --upgrade```\n\nLeGen requires the `yt-dlp` CLI on your system to download remote content automatically.\n\nYou also need to [install FFmpeg](https://ffmpeg.org/download.html)\n\n## Contributing\n\nContributions are welcome. Submit your pull request \u2764\ufe0f\n\n## Issues, Doubts\n\nNot being able to use the software, or encountering an error? open an [issue](https://github.com/matheusbach/legen/issues/new)\n\n## Telegram Group\n\nWelcome and don't be a sick. We are brazilian, but you can write in other language if you want. https://t.me/+c0VRonlcd9Q2YTAx\n\n## Video Tutorials\n\n[PT-BR] [SEMI-OUTDATED] [**Tutorial - LeGen no Google Colab**](https://odysee.com/@legen_software:d/legen_no_colab:0)\n\n## Donations\n\nYou can donate to project using:\nMonero (XMR): ```86HjTCsiaELEoNhH96rTf3ezGMXgKmHjqFrNmca2tesCESdCTZvRvQ9QWQXPGDtmaZhKz4ryHCdZXFzdbmtGahVa5VMLJnx```\nLivePix: https://livepix.gg/legendonate\n\n### Donators\n- Picasso Neves\n- Erasmo de Souza Mora\n- viniciuspro\n- Igor\n- NiNi\n- PopularC\n\n\n## License\n\nThis project is licensed under the terms of the [GNU GPLv3](https://choosealicense.com/licenses/gpl-3.0/).\n",
"bugtrack_url": null,
"license": null,
"summary": "Powerfull toolkit that locally transcribes, translates, and masters subtitles for your media",
"version": "0.19.3",
"project_urls": {
"Homepage": "https://github.com/matheusbach/legen",
"Issue Tracker": "https://github.com/matheusbach/legen/issues"
},
"split_keywords": [
"subtitles",
" whisper",
" translation",
" ffmpeg",
" yt-dlp"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "cb0880d424ff075fefce0d95a269a5c8b7a6ae2dfece58be84084a2237d565bb",
"md5": "2c14650266500af72818dcca4940b114",
"sha256": "dfdf49313005872da3caa1e13bc0268a0ba86980df36bb858304f82c104fad5e"
},
"downloads": -1,
"filename": "legen-0.19.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2c14650266500af72818dcca4940b114",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>=3.9",
"size": 46247,
"upload_time": "2025-11-05T08:19:54",
"upload_time_iso_8601": "2025-11-05T08:19:54.006955Z",
"url": "https://files.pythonhosted.org/packages/cb/08/80d424ff075fefce0d95a269a5c8b7a6ae2dfece58be84084a2237d565bb/legen-0.19.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0961d605683f307d1567c0ec1fa3e2342e15db3c7e6d83c6ffdc68cde7868954",
"md5": "93a01100acd9372c414231e75bf839b2",
"sha256": "6e4f40de55ef7b7f9c4a8fbc1e1fea5a7ce410b90d7c744e07c77bbb3b051a30"
},
"downloads": -1,
"filename": "legen-0.19.3.tar.gz",
"has_sig": false,
"md5_digest": "93a01100acd9372c414231e75bf839b2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.13,>=3.9",
"size": 51840,
"upload_time": "2025-11-05T08:19:56",
"upload_time_iso_8601": "2025-11-05T08:19:56.249455Z",
"url": "https://files.pythonhosted.org/packages/09/61/d605683f307d1567c0ec1fa3e2342e15db3c7e6d83c6ffdc68cde7868954/legen-0.19.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-11-05 08:19:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "matheusbach",
"github_project": "legen",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "deep-translator",
"specs": []
},
{
"name": "ffmpeg-progress-yield",
"specs": []
},
{
"name": "openai-whisper",
"specs": []
},
{
"name": "pysrt",
"specs": []
},
{
"name": "torch",
"specs": []
},
{
"name": "torchaudio",
"specs": [
[
"<",
"2.9"
]
]
},
{
"name": "tqdm",
"specs": []
},
{
"name": "whisper",
"specs": []
},
{
"name": "vidqa",
"specs": []
},
{
"name": "whisperx-legen-fork",
"specs": []
},
{
"name": "gemini-srt-translator",
"specs": []
},
{
"name": "yt-dlp",
"specs": []
}
],
"lcname": "legen"
}
JSON
