Subaligner

https://subaligner.readthedocs.io/en/latest/
Admin
Subaligner is a Python tool and library for automatic subtitle synchronization, transcription, and...
Tokens:6,959
Snippets:111
Trust Score:9.6
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install Subaligner from source

Source: https://subaligner.readthedocs.io/en/latest/_sources/installation.rst.txt

Clone the repository and install Subaligner manually.

```bash
$ git clone git@github.com:baxtree/subaligner.git && cd subaligner
$ pip install -U pip && pip install -U setuptools
$ python setup.py install
```

--------------------------------

### Install Subaligner via PyPI

Source: https://subaligner.readthedocs.io/en/latest/_sources/installation.rst.txt

Install Subaligner and update core build tools.

```bash
$ pip install -U pip && pip install -U setuptools
$ pip install subaligner
```

--------------------------------

### Install Subaligner via Pipenv

Source: https://subaligner.readthedocs.io/en/latest/_sources/installation.rst.txt

Install Subaligner and its variants using Pipenv.

```bash
$ pipenv install subaligner
$ pipenv install 'subaligner[stretch]'
$ pipenv install 'subaligner[dev]'
```

--------------------------------

### Start fresh training

Source: https://subaligner.readthedocs.io/en/latest/_sources/advanced_usage.rst.txt

Initializes a new training session using specified directories for audiovisual files and subtitle files.

```bash
$ subaligner_train -vd av_directory -sd subtitle_directory -tod training_output_directory
```

--------------------------------

### Install optional feature dependencies

Source: https://subaligner.readthedocs.io/en/latest/_sources/installation.rst.txt

Install specific extras for translation, forced alignment, development, or full feature support.

```bash
$ pip install 'subaligner[llm]'
```

```bash
$ pip install 'subaligner[stretch]'
```

```bash
$ pip install 'subaligner[dev]'
```

```bash
$ pip install 'subaligner[harmony]'
```

--------------------------------

### Install FFmpeg dependency

Source: https://subaligner.readthedocs.io/en/latest/_sources/installation.rst.txt

Install the required FFmpeg dependency using system package managers.

```bash
$ apt-get install ffmpeg
```

```bash
$ brew install ffmpeg
```

--------------------------------

### Verify Subaligner CLI

Source: https://subaligner.readthedocs.io/en/latest/_sources/installation.rst.txt

Check available CLI commands after installation.

```bash
(.venv) $ subaligner --help
(.venv) $ subaligner_1pass --help # shortcut for "subaligner -m single"
(.venv) $ subaligner_2pass --help # shortcut for "subaligner -m dual"
(.venv) $ subaligner_batch --help
(.venv) $ subaligner_convert --help
(.venv) $ subaligner_train --help
(.venv) $ subaligner_tune --help
```

--------------------------------

### Install Subaligner via pipx

Source: https://subaligner.readthedocs.io/en/latest/_sources/installation.rst.txt

Install Subaligner and its variants using pipx for isolated environments.

```bash
$ pipx install subaligner
$ pipx install 'subaligner[stretch]'
$ pipx install 'subaligner[dev]'
```

--------------------------------

### Install eSpeak dependencies

Source: https://subaligner.readthedocs.io/en/latest/_sources/installation.rst.txt

Install eSpeak libraries required for specific Subaligner features.

```bash
$ apt-get install espeak libespeak1 libespeak-dev espeak-data
```

```bash
$ brew install espeak
```

--------------------------------

### Ignore sound effects

Source: https://subaligner.readthedocs.io/en/latest/_sources/advanced_usage.rst.txt

Filters out subtitles containing sound effects by defining start and end markers.

```bash
$ subaligner_train -vd av_directory -sd subtitle_directory -tod training_output_directory --sound_effect_start_marker "(" --sound_effect_end_marker ")"
```

--------------------------------

### Run Subaligner on Windows with Docker

Source: https://subaligner.readthedocs.io/en/latest/_sources/installation.rst.txt

Pull and run the Subaligner image on Windows using Docker Desktop.

```bash
docker pull baxtree/subaligner
docker run -v "/d/media":/media -w "/media" -it baxtree/subaligner bash
```

--------------------------------

### Run unit tests

Source: https://subaligner.readthedocs.io/en/latest/_sources/test.rst.txt

Executes the standard unit test suite.

```bash
$ make test
```

--------------------------------

### Configure FFmpeg or Libav Path

Source: https://subaligner.readthedocs.io/en/latest/_sources/usage.rst.txt

Set the FFMPEG_PATH environment variable to point to a custom FFmpeg or Libav binary.

```bash
(.venv) $ export FFMPEG_PATH=/path/to/ffmpeg
(.venv) $ subaligner -m dual -v video.mp4 -s subtitle.srt
or
(.venv) $ FFMPEG_PATH=/path/to/ffmpeg subaligner -m dual -v video.mp4 -s subtitle.srt
or when using `Libav<https://libav.org/>`_
(.venv) $ FFMPEG_PATH=/path/to/avconv subaligner -m dual -v video.mp4 -s subtitle.srt
```

--------------------------------

### Configure Training Hyperparameters

Source: https://subaligner.readthedocs.io/en/latest/advanced_usage.html

List of command-line flags for manually adjusting training hyperparameters.

```bash
-bs BATCH_SIZE, --batch_size BATCH_SIZE
                    Number of 32ms samples at each training step
-do DROPOUT, --dropout DROPOUT
    Dropout rate between 0 and 1 used at the end of each intermediate hidden layer
-e EPOCHS, --epochs EPOCHS
    Total training epochs
-p PATIENCE, --patience PATIENCE
    Number of epochs with no improvement after which training will be stopped
-fhs FRONT_HIDDEN_SIZE, --front_hidden_size FRONT_HIDDEN_SIZE
    Number of neurons in the front LSTM or Conv1D layer
-bhs BACK_HIDDEN_SIZE, --back_hidden_size BACK_HIDDEN_SIZE
    Comma-separated numbers of neurons in the back Dense layers
-lr LEARNING_RATE, --learning_rate LEARNING_RATE
    Learning rate of the optimiser
-nt {lstm,bi_lstm,conv_1d}, --network_type {lstm,bi_lstm,conv_1d}
    Network type
-vs VALIDATION_SPLIT, --validation_split VALIDATION_SPLIT
    Fraction between 0 and 1 of the training data to be used as validation data
-o {adadelta,adagrad,adam,adamax,ftrl,nadam,rmsprop,sgd}, --optimizer {adadelta,adagrad,adam,adamax,ftrl,nadam,rmsprop,sgd}
    TensorFlow optimizer
```

--------------------------------

### Enable Experimental Stretching

Source: https://subaligner.readthedocs.io/en/latest/_sources/usage.rst.txt

Use the -so flag to enable experimental subtitle stretching, requiring the subaligner[stretch] package.

```bash
(.venv) $ subaligner -m dual -v video.mp4 -s subtitle.srt -so
```

--------------------------------

### Run integration tests

Source: https://subaligner.readthedocs.io/en/latest/_sources/test.rst.txt

Executes the integration test suite.

```bash
$ make test-int
```

--------------------------------

### Run Subaligner with Docker

Source: https://subaligner.readthedocs.io/en/latest/_sources/usage.rst.txt

Commands to pull the Docker image and execute alignment in single or dual mode using local or remote files.

```bash
$ docker pull baxtree/subaligner
$ docker run -v `pwd`:`pwd` -w `pwd` -it baxtree/subaligner subaligner -m single -v video.mp4 -s subtitle.srt
$ docker run -v `pwd`:`pwd` -w `pwd` -it baxtree/subaligner subaligner -m dual -v video.mp4 -s subtitle.srt
$ docker run -it baxtree/subaligner subaligner -m single -v https://example.com/video.mp4 -s https://example.com/subtitle.srt -o subtitle_aligned.srt
$ docker run -it baxtree/subaligner subaligner -m dual -v https://example.com/video.mp4 -s https://example.com/subtitle.srt -o subtitle_aligned.srt
```

--------------------------------

### Customize Tuning Configuration

Source: https://subaligner.readthedocs.io/en/latest/advanced_usage.html

Optional flags to refine the hyperparameter tuning process.

```bash
-ept EPOCHS_PER_TRAIL, --epochs_per_trail EPOCHS_PER_TRAIL
    Number of training epochs for each trial
-t TRAILS, --trails TRAILS
    Number of tuning trials
-nt {lstm,bi_lstm,conv_1d}, --network_type {lstm,bi_lstm,conv_1d}
    Network type
-utd, --use_training_dump
    Use training dump instead of files in the video or subtitle directory
```

--------------------------------

### Resume training

Source: https://subaligner.readthedocs.io/en/latest/_sources/advanced_usage.rst.txt

Continues a previous training session from a specific epoch. Ensure the epoch count is greater than previously completed ones.

```bash
$ subaligner_train -vd av_directory -sd subtitle_directory -tod training_output_directory -e 200 -r
```

--------------------------------

### Convert subtitle formats

Source: https://subaligner.readthedocs.io/en/latest/_sources/advanced_usage.rst.txt

Convert subtitle files between different formats.

```bash
$ subaligner_convert -i subtitle.srt -o subtitle.vtt
```

--------------------------------

### Configure Processing Timeouts

Source: https://subaligner.readthedocs.io/en/latest/_sources/usage.rst.txt

Command-line arguments for setting maximum wait times for media processing and segment alignment.

```bash
-mpt MEDIA_PROCESS_TIMEOUT, --media_process_timeout MEDIA_PROCESS_TIMEOUT
                    Maximum waiting time in seconds when processing media files
-sat SEGMENT_ALIGNMENT_TIMEOUT, --segment_alignment_timeout SEGMENT_ALIGNMENT_TIMEOUT
                    Maximum waiting time in seconds when aligning each segment
```

--------------------------------

### Batch alignment

Source: https://subaligner.readthedocs.io/en/latest/_sources/usage.rst.txt

Runs alignment processes across entire directories of videos and subtitles.

```bash
(.venv) $ subaligner_batch -m single -vd videos/ -sd subtitles/ -od aligned_subtitles/
(.venv) $ subaligner_batch -m dual -vd videos/ -sd subtitles/ -od aligned_subtitles/
(.venv) $ subaligner_batch -m dual -vd videos/ -sd subtitles/ -od aligned_subtitles/ -of ttml
```

--------------------------------

### Specify Output Location

Source: https://subaligner.readthedocs.io/en/latest/_sources/usage.rst.txt

Define a custom file path for the aligned subtitle output.

```bash
(.venv) $ subaligner -m dual -v video.mp4 -s subtitle.srt -o /path/to/the/output/subtitle.srt
```

--------------------------------

### Run test coverage

Source: https://subaligner.readthedocs.io/en/latest/_sources/test.rst.txt

Generates a test coverage report.

```bash
$ make coverage
```

--------------------------------

### Run Subaligner as a Python Module

Source: https://subaligner.readthedocs.io/en/latest/_sources/usage.rst.txt

Execute the module directly using the Python interpreter.

```bash
$ python -m subaligner -m single -v video.mp4 -s subtitle.srt
$ python -m subaligner -m dual -v video.mp4 -s subtitle.srt
```

--------------------------------

### Run Subaligner in Docker

Source: https://subaligner.readthedocs.io/en/latest/_sources/installation.rst.txt

Execute Subaligner within a containerized environment.

```bash
$ docker run -v `pwd`:`pwd` -w `pwd` -it baxtree/subaligner bash
```

--------------------------------

### Run alignments after training

Source: https://subaligner.readthedocs.io/en/latest/_sources/advanced_usage.rst.txt

Applies a trained model to synchronize subtitles using either single or dual alignment modes.

```bash
$ subaligner -m single -v video.mp4 -s subtitle.srt -tod training_output_directory
$ subaligner -m dual -v video.mp4 -s subtitle.srt -tod training_output_directory
```

--------------------------------

### Run Alignments with pipx

Source: https://subaligner.readthedocs.io/en/latest/_sources/usage.rst.txt

Execute Subaligner using pipx for isolated environment management.

```bash
$ pipx run subaligner -m single -v video.mp4 -s subtitle.srt
$ pipx run subaligner -m dual -v video.mp4 -s subtitle.srt
```

--------------------------------

### Transcribe and translate

Source: https://subaligner.readthedocs.io/en/latest/_sources/usage.rst.txt

Transcribes audiovisual files and generates translated subtitles in one process.

```bash
(.venv) $ subaligner -m transcribe -v video.mp4 -ml src -mr whisper -mf small -tr helsinki-nlp -o subtitle_aligned.srt -t src,tgt
```

--------------------------------

### Run hyperparameter tuning

Source: https://subaligner.readthedocs.io/en/latest/_sources/advanced_usage.rst.txt

Execute automated hyperparameter tuning using the Tree-structured Parzen Estimator approach.

```bash
$ subaligner_tune -vd av_directory -sd subtitle_directory -tod training_output_directory
```

--------------------------------

### Alignment on multiple subtitles

Source: https://subaligner.readthedocs.io/en/latest/_sources/usage.rst.txt

Aligns multiple subtitle files against a single media file.

```bash
(.venv) $ subaligner -m script -v video.mp4 -s subtitle_lang_1.txt -s subtitle_lang_2.txt
(.venv) $ subaligner -m script -v video.mp4 -s subtitle_lang_1.txt subtitle_lang_2.txt
```

--------------------------------

### Run tests with target Python versions

Source: https://subaligner.readthedocs.io/en/latest/_sources/test.rst.txt

Executes tests across all supported Python versions.

```bash
$ make test-all
```

--------------------------------

### Convert and translate subtitles

Source: https://subaligner.readthedocs.io/en/latest/_sources/advanced_usage.rst.txt

Convert subtitle formats while simultaneously translating the content.

```bash
$ subaligner_convert --languages
$ subaligner_convert -i subtitle_en.srt -o subtitle_zh.vtt -t eng,zho
```

--------------------------------

### Transcribe audiovisual files

Source: https://subaligner.readthedocs.io/en/latest/_sources/usage.rst.txt

Uses LLMs to generate subtitles from media files with various model configurations.

```bash
(.venv) $ subaligner -m transcribe -v video.mp4 -ml eng -mr whisper -mf small -o subtitle_aligned.srt
(.venv) $ subaligner -m transcribe -v video.mp4 -ml zho -mr whisper -mf medium -o subtitle_aligned.srt
(.venv) $ subaligner -m transcribe -v video.mp4 -ml eng -mr whisper -mf turbo -ip "your initial prompt" -o subtitle_aligned.srt
(.venv) $ subaligner -m transcribe -v video.mp4 -ml eng -mr whisper -mf turbo -ip "your initial prompt" --word_time_codes -o raw_subtitle.json
(.venv) $ subaligner -m transcribe -v video.mp4 -s subtitle.srt -ml eng -mr whisper -mf turbo -o subtitle_aligned.srt
(.venv) $ subaligner -m transcribe -v video.mp4 -s subtitle.srt --use_prior_prompting -ml eng -mr whisper -mf turbo -o subtitle_aligned.srt
```

--------------------------------

### Display completed epochs

Source: https://subaligner.readthedocs.io/en/latest/_sources/advanced_usage.rst.txt

Retrieves the count of epochs already completed in a training output directory.

```bash
$ subaligner_train -dde -tod training_output_directory
```

--------------------------------

### Dual-stage alignment

Source: https://subaligner.readthedocs.io/en/latest/_sources/usage.rst.txt

Performs low-level subtitle shifting with higher latency and optional segment stretching.

```bash
(.venv) $ subaligner -m dual -v video.mp4 -s subtitle.srt
(.venv) $ subaligner -m dual -v https://example.org/video.mp4 -s https://example.org/subtitle.srt -o subtitle_aligned.srt
```

--------------------------------

### Single-stage alignment

Source: https://subaligner.readthedocs.io/en/latest/_sources/usage.rst.txt

Performs high-level global subtitle shifting with lower latency.

```bash
(.venv) $ subaligner -m single -v video.mp4 -s subtitle.srt
(.venv) $ subaligner -m single -v https://example.org/video.mp4 -s https://example.org/subtitle.srt -o subtitle_aligned.srt
```

--------------------------------

### Alignment on segmented plain texts

Source: https://subaligner.readthedocs.io/en/latest/_sources/usage.rst.txt

Aligns subtitles using plain text files where double newlines act as delimiters.

```bash
(.venv) $ subaligner -m script -v video.mp4 -s subtitle.txt -o subtitle_aligned.srt
(.venv) $ subaligner -m script -v video.mp4 -s subtitle.txt --word_time_codes -o raw_subtitle.json
(.venv) $ subaligner -m script -v https://example.com/video.mp4 -s https://example.com/subtitle.txt -o subtitle_aligned.srt
```

--------------------------------

### Re-configure timeouts

Source: https://subaligner.readthedocs.io/en/latest/_sources/advanced_usage.rst.txt

Defines maximum wait times for media processing and feature embedding tasks.

```bash
  -fet FEATURE_EMBEDDING_TIMEOUT, --feature_embedding_timeout FEATURE_EMBEDDING_TIMEOUT
                        Maximum waiting time in seconds when embedding features of media files
  -mpt MEDIA_PROCESS_TIMEOUT, --media_process_timeout MEDIA_PROCESS_TIMEOUT
                        Maximum waiting time in seconds when processing media files
```

--------------------------------

### Translate subtitles without format change

Source: https://subaligner.readthedocs.io/en/latest/_sources/advanced_usage.rst.txt

Translate subtitle files while maintaining the original format.

```bash
$ subaligner_convert --languages
$ subaligner_convert -i subtitle_en.srt -o subtitle_es.srt -t eng,spa
```

--------------------------------

### Reuse embeddings

Source: https://subaligner.readthedocs.io/en/latest/_sources/advanced_usage.rst.txt

Skips the feature embedding process by reusing existing dumps, useful when training new models on the same dataset.

```bash
$ subaligner_train -utd -tod training_output_directory
```

--------------------------------

### Translative alignment

Source: https://subaligner.readthedocs.io/en/latest/_sources/usage.rst.txt

Performs alignment combined with translation using specific language codes and translation models.

```bash
(.venv) $ subaligner --languages
(.venv) $ subaligner -m single -v video.mp4 -s subtitle.srt -t src,tgt
(.venv) $ subaligner -m dual -v video.mp4 -s subtitle.srt -t src,tgt
(.venv) $ subaligner -m script -v video.mp4 -s subtitle.txt -o subtitle_aligned.srt -t src,tgt
(.venv) $ subaligner -m dual -v video.mp4 -s subtitle.srt -tr helsinki-nlp -o subtitle_aligned.srt -t src,tgt
(.venv) $ subaligner -m dual -v video.mp4 -s subtitle.srt -tr facebook-mbart -tf large -o subtitle_aligned.srt -t src,tgt
(.venv) $ subaligner -m dual -v video.mp4 -s subtitle.srt -tr facebook-m2m100 -tf small -o subtitle_aligned.srt -t src,tgt
(.venv) $ subaligner -m dual -v video.mp4 -s subtitle.srt -tr whisper -tf small -o subtitle_aligned.srt -t src,eng
```

--------------------------------

### Manual subtitle shift

Source: https://subaligner.readthedocs.io/en/latest/_sources/usage.rst.txt

Shifts subtitle timestamps by a specified number of seconds.

```bash
(.venv) $ subaligner -m shift --subtitle_path subtitle.srt -os 5.5
(.venv) $ subaligner -m shift --subtitle_path subtitle.srt -os -5.5 -o subtitle_shifted.srt
```

--------------------------------

### Alignment on embedded subtitles

Source: https://subaligner.readthedocs.io/en/latest/_sources/usage.rst.txt

Aligns subtitles embedded directly within a video file.

```bash
(.venv) $ subaligner -m single -v video.mkv -s embedded:stream_index=0 -o subtitle_aligned.srt
(.venv) $ subaligner -m dual -v video.mkv -s embedded:stream_index=0 -o subtitle_aligned.srt
```

--------------------------------

### Train with embedded subtitles

Source: https://subaligner.readthedocs.io/en/latest/_sources/advanced_usage.rst.txt

Extracts subtitles directly from audiovisual files using a selector, omitting the need for a separate subtitle directory.

```bash
$ subaligner_train -vd av_directory -ess embedded:stream_index=0,file_extension=srt -tod training_output_directory
```

--------------------------------

### subaligner.transcriber.Transcriber

Source: https://subaligner.readthedocs.io/en/latest/_sources/subaligner.transcriber.rst.txt

The Transcriber class is the primary interface for audio transcription tasks. It provides methods to process audio files and extract text content.

```APIDOC
## class subaligner.transcriber.Transcriber

### Description
Provides methods for transcribing audio files into text format.

### Methods
- **transcribe(audio_file_path: str, language: str = 'en') -> str**
  - Transcribes the provided audio file into text.
  - **Parameters**:
    - **audio_file_path** (str) - Required - The local file path to the audio file.
    - **language** (str) - Optional - The language code for the transcription (default: 'en').
  - **Returns**:
    - (str) - The transcribed text content.
```
Tokens:
Raw