Skip to content

Commit b64a3c2

Browse files
baxtreebaxtree
committed
update README and dependencies
1 parent 2d3713c commit b64a3c2

File tree

5 files changed

+196
-166
lines changed

5 files changed

+196
-166
lines changed

‎.github/workflows/dockerhub-extra.yml‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -44,8 +44,10 @@ jobs:
4444
id: docker_build_latest
4545
uses: docker/build-push-action@v4
4646
with:
47-
context: .
47+
context: ./docker
4848
file: "./docker/Dockerfile-Ubuntu20"
49+
build-args: |
50+
"RELEASE_VERSION=${{ env.SUBALIGNER_TAG }}"
4951
platforms: linux/amd64,linux/arm64
5052
allow: network.host
5153
github-token: ${{ github.token }}

‎.github/workflows/lint-charts.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ env:
1212

1313
jobs:
1414
lint-helm-charts:
15-
runs-on: ubuntu-20.04
15+
runs-on: ubuntu-latest
1616

1717
steps:
1818
- name: Checkout sources

‎README.md‎

Lines changed: 188 additions & 161 deletions
Original file line numberDiff line numberDiff line change
@@ -17,186 +17,213 @@ Video/Audio: MP4, WebM, Ogg, 3GP, FLV, MOV, Matroska, MPEG TS, WAV, MP3, AAC, FL
1717

1818
:information_source: <small style="line-height: 1.2;">Subaligner relies on file extensions as default hints to process a wide range of audiovisual or subtitle formats. It is recommended to use extensions widely acceppted by the community to ensure compatibility.</small>
1919

20-
## Dependencies
21-
Required by basic: [FFmpeg](https://www.ffmpeg.org/)
22-
```
23-
$ apt-get install ffmpeg
24-
```
25-
or
26-
```
27-
$ brew install ffmpeg
28-
```
20+
## Dependant package
21+
Required by the basic installation: [FFmpeg](https://www.ffmpeg.org/)
22+
<details>
23+
<summary>Install FFmpeg</summary>
24+
<pre><code>apt-get install ffmpeg</code></pre>
25+
<pre><code>brew install ffmpeg</code></pre>
26+
</details>
2927

3028
## Basic Installation
31-
```
32-
$ pip install -U pip && pip install -U setuptools wheel
33-
$ pip install subaligner
34-
```
35-
or install from source:
36-
```
37-
$ git clone git@github.com:baxtree/subaligner.git && cd subaligner
38-
$ pip install -U pip && pip install -U setuptools
39-
$ python setup.py install
40-
```
29+
<details>
30+
<summary>Install from PyPI</summary>
31+
<pre><code>pip install -U pip && pip install -U setuptools wheel</code></pre>
32+
<pre><code>pip install subaligner</code></pre>
33+
</details>
34+
<details>
35+
<summary>Install from source</summary>
36+
<pre><code>git clone git@github.com:baxtree/subaligner.git && cd subaligner</code></pre>
37+
<pre><code>pip install -U pip && pip install -U setuptools</code></pre>
38+
<pre><code>pip install .</code></pre>
39+
</details>
4140
:information_source: <small style="line-height: 1.2;">It is highly recommended creating a virtual environment prior to installation.</small>
4241

4342
## Installation with Optional Packages Supporting Additional Features
44-
```
45-
# Install dependencies for enabling translation and transcription
46-
47-
$ pip install 'subaligner[llm]'
48-
```
49-
```
50-
# Install dependencies for enabling forced alignment
51-
52-
$ pip install 'setuptools<65.0.0'
53-
$ pip install 'subaligner[stretch]'
54-
```
55-
```
56-
# Install dependencies for setting up the development environment
57-
58-
$ pip install 'setuptools<65.0.0'
59-
$ pip install 'subaligner[dev]'
60-
```
61-
Note that both `subaligner[stretch]` and `subaligner[dev]` require additional dependencies to be pre-installed:
62-
```
63-
$ apt-get install espeak libespeak1 libespeak-dev espeak-data
64-
```
65-
or
66-
```
67-
$ brew install espeak
68-
```
69-
To install all supported features:
70-
```
71-
$ pip install 'setuptools<65.0.0'
72-
$ pip install 'subaligner[harmony]'
73-
```
43+
<details>
44+
<summary>Install dependencies for enabling translation and transcription</summary>
45+
<pre><code>pip install 'subaligner[llm]'</code></pre>
46+
</details>
47+
48+
<details>
49+
<summary>Install dependencies for enabling forced alignment</summary>
50+
<pre><code>pip install 'setuptools<65.0.0'</code></pre>
51+
<pre><code>pip install 'subaligner[stretch]'</code></pre>
52+
</details>
53+
54+
<details>
55+
<summary>Install dependencies for setting up the development environment</summary>
56+
<pre><code>pip install 'setuptools<65.0.0'</code></pre>
57+
<pre><code>pip install 'subaligner[dev]'</code></pre>
58+
</details>
59+
60+
61+
<details>
62+
<summary>Install all extra dependencies</summary>
63+
<pre><code>pip install 'setuptools<65.0.0'</code></pre>
64+
<pre><code>pip install 'subaligner[harmony]'</code></pre>
65+
</details>
66+
67+
Note that `subaligner[stretch]`, `subaligner[dev]` and `subaligner[harmony]` require [eSpeak](https://espeak.sourceforge.net/) to be pre-installed:
68+
<details>
69+
<summary>Install eSpeak</summary>
70+
<pre><code>apt-get install espeak libespeak1 libespeak-dev espeak-data</code></pre>
71+
<pre><code>brew install espeak</code></pre>
72+
</details>
7473

7574
## Container Support
76-
If you prefer using a containerised environment over installing everything locally, run:
75+
If you prefer using a containerised environment over installing everything locally:
76+
<details>
77+
<summary>Run subaligner with a container</summary>
78+
<pre><code>docker run -v `pwd`:`pwd` -w `pwd` -it baxtree/subaligner bash</code></pre>
79+
</details>
7780

78-
```
79-
$ docker run -v `pwd`:`pwd` -w `pwd` -it baxtree/subaligner bash
80-
```
8181
For Windows users, you can use Windows Subsystem for Linux ([WSL](https://learn.microsoft.com/en-us/windows/wsl/install)) to install Subaligner.
8282
Alternatively, you can use [Docker Desktop](https://docs.docker.com/docker-for-windows/install/) to pull and run the image.
83-
Assuming your media assets are stored under `d:\media`, open built-in command prompt, PowerShell, or Windows Terminal and run:
84-
```
85-
docker pull baxtree/subaligner
86-
docker run -v "/d/media":/media -w "/media" -it baxtree/subaligner bash
87-
```
83+
Assuming your media assets are stored under `d:\media`, open built-in command prompt, PowerShell, or Windows Terminal:
84+
<details>
85+
<summary>Run the subaligner container on Windows</summary>
86+
<pre><code>docker pull baxtree/subaligner</code></pre>
87+
<pre><code>docker run -v "/d/media":/media -w "/media" -it baxtree/subaligner bash</code></pre>
88+
</details>
8889

8990
## Usage
90-
```
91-
# Single-stage alignment (high-level shift with lower latency)
92-
93-
$ subaligner -m single -v video.mp4 -s subtitle.srt
94-
$ subaligner -m single -v https://example.com/video.mp4 -s https://example.com/subtitle.srt -o subtitle_aligned.srt
95-
```
96-
```
97-
# Dual-stage alignment (low-level shift with higher latency)
98-
99-
$ subaligner -m dual -v video.mp4 -s subtitle.srt
100-
$ subaligner -m dual -v https://example.com/video.mp4 -s https://example.com/subtitle.srt -o subtitle_aligned.srt
101-
```
102-
```
103-
# Generate subtitles by transcribing audiovisual files
104-
$ subaligner -m transcribe -v video.mp4 -ml eng -mr whisper -mf small -o subtitle_aligned.srt
105-
$ subaligner -m transcribe -v video.mp4 -ml zho -mr whisper -mf medium -o subtitle_aligned.srt
106-
$ subaligner -m transcribe -v video.mp4 -ml eng -mr whisper -mf turbo -ip "your initial prompt" -o subtitle_aligned.srt
107-
$ subaligner -m transcribe -v video.mp4 -ml eng -mr whisper -mf turbo -ip "your initial prompt" --word_time_codes -o raw_subtitle.json
108-
$ subaligner -m transcribe -v video.mp4 -s subtitle.srt -ml eng -mr whisper -mf turbo -o subtitle_aligned.srt
109-
$ subaligner -m transcribe -v video.mp4 -s subtitle.srt --use_prior_prompting -ml eng -mr whisper -mf turbo -o subtitle_aligned.srt
110-
111-
```
112-
```
113-
# Alignment on segmented plain texts (double newlines as the delimiter)
114-
115-
$ subaligner -m script -v video.mp4 -s subtitle.txt -o subtitle_aligned.srt
116-
$ subaligner -m script -v video.mp4 -s subtitle.txt --word_time_codes -o raw_subtitle.json
117-
$ subaligner -m script -v https://example.com/video.mp4 -s https://example.com/subtitle.txt -o subtitle_aligned.srt
118-
```
119-
```
120-
# Alignment on multiple subtitles against the single media file
121-
122-
$ subaligner -m script -v video.mp4 -s subtitle_lang_1.txt -s subtitle_lang_2.txt
123-
$ subaligner -m script -v video.mp4 -s subtitle_lang_1.txt subtitle_lang_2.txt
124-
```
125-
```
126-
# Alignment on embedded subtitles
127-
128-
$ subaligner -m single -v video.mkv -s embedded:stream_index=0 -o subtitle_aligned.srt
129-
$ subaligner -m dual -v video.mkv -s embedded:stream_index=0 -o subtitle_aligned.srt
130-
```
131-
```
132-
# Translative alignment with the ISO 639-3 language code pair (src,tgt)
133-
134-
$ subaligner --languages
135-
$ subaligner -m single -v video.mp4 -s subtitle.srt -t src,tgt
136-
$ subaligner -m dual -v video.mp4 -s subtitle.srt -t src,tgt
137-
$ subaligner -m script -v video.mp4 -s subtitle.txt -o subtitle_aligned.srt -t src,tgt
138-
$ subaligner -m dual -v video.mp4 -s subtitle.srt -tr helsinki-nlp -o subtitle_aligned.srt -t src,tgt
139-
$ subaligner -m dual -v video.mp4 -s subtitle.srt -tr facebook-mbart -tf large -o subtitle_aligned.srt -t src,tgt
140-
$ subaligner -m dual -v video.mp4 -s subtitle.srt -tr facebook-m2m100 -tf small -o subtitle_aligned.srt -t src,tgt
141-
$ subaligner -m dual -v video.mp4 -s subtitle.srt -tr whisper -tf small -o subtitle_aligned.srt -t src,eng
142-
```
143-
```
144-
# Transcribe audiovisual files and generate translated subtitles
145-
146-
$ subaligner -m transcribe -v video.mp4 -ml src -mr whisper -mf small -tr helsinki-nlp -o subtitle_aligned.srt -t src,tgt
147-
```
148-
```
149-
# Shift subtitle manually by offset in seconds
150-
151-
$ subaligner -m shift --subtitle_path subtitle.srt -os 5.5
152-
$ subaligner -m shift --subtitle_path subtitle.srt -os -5.5 -o subtitle_shifted.srt
153-
```
154-
```
155-
# Run batch alignment against directories
156-
157-
$ subaligner_batch -m single -vd videos/ -sd subtitles/ -od aligned_subtitles/
158-
$ subaligner_batch -m dual -vd videos/ -sd subtitles/ -od aligned_subtitles/
159-
$ subaligner_batch -m dual -vd videos/ -sd subtitles/ -od aligned_subtitles/ -of ttml
160-
```
161-
```
162-
# Run alignments with pipx
163-
164-
$ pipx run subaligner -m single -v video.mp4 -s subtitle.srt
165-
$ pipx run subaligner -m dual -v video.mp4 -s subtitle.srt
166-
```
167-
```
168-
# Run the module as a script
169-
$ python -m subaligner -m single -v video.mp4 -s subtitle.srt
170-
$ python -m subaligner -m dual -v video.mp4 -s subtitle.srt
171-
```
172-
```
173-
# Run alignments with the docker image
174-
175-
$ docker pull baxtree/subaligner
176-
$ docker run -v `pwd`:`pwd` -w `pwd` -it baxtree/subaligner subaligner -m single -v video.mp4 -s subtitle.srt
177-
$ docker run -v `pwd`:`pwd` -w `pwd` -it baxtree/subaligner subaligner -m dual -v video.mp4 -s subtitle.srt
178-
$ docker run -it baxtree/subaligner subaligner -m single -v https://example.com/video.mp4 -s https://example.com/subtitle.srt -o subtitle_aligned.srt
179-
$ docker run -it baxtree/subaligner subaligner -m dual -v https://example.com/video.mp4 -s https://example.com/subtitle.srt -o subtitle_aligned.srt
180-
```
91+
<details>
92+
<summary>Single-stage alignment (high-level shift with lower latency)</summary>
93+
<pre><code>subaligner -m single -v video.mp4 -s subtitle.srt</code></pre>
94+
<pre><code>subaligner -m single -v https://example.com/video.mp4 -s https://example.com/subtitle.srt -o subtitle_aligned.srt</code></pre>
95+
</details>
96+
97+
<details>
98+
<summary>Dual-stage alignment (low-level shift with higher latency)</summary>
99+
<pre><code>subaligner -m dual -v video.mp4 -s subtitle.srt</code></pre>
100+
<pre><code>subaligner -m dual -v https://example.com/video.mp4 -s https://example.com/subtitle.srt -o subtitle_aligned.srt</code></pre>
101+
</details>
102+
103+
<details>
104+
<summary>Generate subtitles by transcribing audiovisual files</summary>
105+
<pre><code>subaligner -m transcribe -v video.mp4 -ml eng -mr whisper -mf small -o subtitle_aligned.srt</code></pre>
106+
<pre><code>subaligner -m transcribe -v video.mp4 -ml zho -mr whisper -mf medium -o subtitle_aligned.srt</code></pre>
107+
</details>
108+
109+
<details>
110+
<summary>Pass in a global prompt for the entire audio transcription</summary>
111+
<pre><code>subaligner -m transcribe -v video.mp4 -ml eng -mr whisper -mf turbo -ip "your initial prompt" -o subtitle_aligned.srt</code></pre>
112+
</details>
113+
114+
<details>
115+
<summary>Use the full subtitle content as a prompt</summary>
116+
<pre><code>subaligner -m transcribe -v video.mp4 -s subtitle.srt -ml eng -mr whisper -mf turbo -o subtitle_aligned.srt</code></pre>
117+
</details>
118+
119+
<details>
120+
<summary>Use the previous subtitle segment as the prompt when transcribing the following segment</summary>
121+
<pre><code>subaligner -m transcribe -v video.mp4 -s subtitle.srt --use_prior_prompting -ml eng -mr whisper -mf turbo -o subtitle_aligned.srt</code></pre>
122+
</details>
123+
124+
(For details on the prompt crafting for transcription, please refer to [Whisper prompting guide](https://cookbook.openai.com/examples/whisper_prompting_guide).)
125+
126+
<details>
127+
<summary>Alignment on segmented plain texts (double newlines as the delimiter)</summary>
128+
<pre><code>subaligner -m script -v video.mp4 -s subtitle.txt -o subtitle_aligned.srt</code></pre>
129+
<pre><code>subaligner -m script -v https://example.com/video.mp4 -s https://example.com/subtitle.txt -o subtitle_aligned.srt</code></pre>
130+
</details>
131+
132+
<details>
133+
<summary>Generate JSON raw subtitle with per-word timings</summary>
134+
<pre><code>subaligner -m transcribe -v video.mp4 -ml eng -mr whisper -mf turbo -ip "your initial prompt" --word_time_codes -o raw_subtitle.json</code></pre>
135+
<pre><code>subaligner -m script -v video.mp4 -s subtitle.txt --word_time_codes -o raw_subtitle.json</code></pre>
136+
</details>
137+
138+
139+
<details>
140+
<summary>Alignment on multiple subtitles against the single media file</summary>
141+
<pre><code>subaligner -m script -v video.mp4 -s subtitle_lang_1.txt -s subtitle_lang_2.txt</code></pre>
142+
<pre><code>subaligner -m script -v video.mp4 -s subtitle_lang_1.txt subtitle_lang_2.txt</code></pre>
143+
</details>
144+
145+
<details>
146+
<summary>Alignment on embedded subtitles</summary>
147+
<pre><code>subaligner -m single -v video.mkv -s embedded:stream_index=0 -o subtitle_aligned.srt</code></pre>
148+
<pre><code>subaligner -m dual -v video.mkv -s embedded:stream_index=0 -o subtitle_aligned.srt</code></pre>
149+
</details>
150+
151+
<details>
152+
<summary>Translative alignment with the ISO 639-3 language code pair (src,tgt)</summary>
153+
<pre><code>subaligner --languages</code></pre>
154+
<pre><code>subaligner -m single -v video.mp4 -s subtitle.srt -t src,tgt</code></pre>
155+
<pre><code>subaligner -m dual -v video.mp4 -s subtitle.srt -t src,tgt</code></pre>
156+
<pre><code>subaligner -m script -v video.mp4 -s subtitle.txt -o subtitle_aligned.srt -t src,tgt</code></pre>
157+
<pre><code>subaligner -m dual -v video.mp4 -s subtitle.srt -tr helsinki-nlp -o subtitle_aligned.srt -t src,tgt</code></pre>
158+
<pre><code>subaligner -m dual -v video.mp4 -s subtitle.srt -tr facebook-mbart -tf large -o subtitle_aligned.srt -t src,tgt</code></pre>
159+
<pre><code>subaligner -m dual -v video.mp4 -s subtitle.srt -tr facebook-m2m100 -tf small -o subtitle_aligned.srt -t src,tgt</code></pre>
160+
<pre><code>subaligner -m dual -v video.mp4 -s subtitle.srt -tr whisper -tf small -o subtitle_aligned.srt -t src,eng</code></pre>
161+
</details>
162+
163+
<details>
164+
<summary>Transcribe audiovisual files and generate translated subtitles</summary>
165+
<pre><code>subaligner -m transcribe -v video.mp4 -ml src -mr whisper -mf small -tr helsinki-nlp -o subtitle_aligned.srt -t src,tgt</code></pre>
166+
</details>
167+
168+
169+
<details>
170+
<summary>Shift subtitle manually by offset in seconds</summary>
171+
<pre><code>subaligner -m shift --subtitle_path subtitle.srt -os 5.5</code></pre>
172+
<pre><code>subaligner -m shift --subtitle_path subtitle.srt -os -5.5 -o subtitle_shifted.srt</code></pre>
173+
</details>
174+
175+
<details>
176+
<summary>Run batch alignment against directories</summary>
177+
<pre><code>subaligner_batch -m single -vd videos/ -sd subtitles/ -od aligned_subtitles/</code></pre>
178+
<pre><code>subaligner_batch -m dual -vd videos/ -sd subtitles/ -od aligned_subtitles/</code></pre>
179+
<pre><code>subaligner_batch -m dual -vd videos/ -sd subtitles/ -od aligned_subtitles/ -of ttml</code></pre>
180+
</details>
181+
182+
<details>
183+
<summary>Run alignments with pipx</summary>
184+
<pre><code>pipx run subaligner -m single -v video.mp4 -s subtitle.srt</code></pre>
185+
<pre><code>pipx run subaligner -m dual -v video.mp4 -s subtitle.srt</code></pre>
186+
</details>
187+
188+
<details>
189+
<summary>Run the module as a script</summary>
190+
<pre><code>python -m subaligner -m single -v video.mp4 -s subtitle.srt</code></pre>
191+
<pre><code>python -m subaligner -m dual -v video.mp4 -s subtitle.srt</code></pre>
192+
</details>
193+
194+
<details>
195+
<summary>Run alignments with the docker image</summary>
196+
<pre><code>docker pull baxtree/subaligner</code></pre>
197+
<pre><code>docker run -v `pwd`:`pwd` -w `pwd` -it baxtree/subaligner subaligner -m single -v video.mp4 -s subtitle.srt</code></pre>
198+
<pre><code>docker run -v `pwd`:`pwd` -w `pwd` -it baxtree/subaligner subaligner -m dual -v video.mp4 -s subtitle.srt</code></pre>
199+
<pre><code>docker run -it baxtree/subaligner subaligner -m single -v https://example.com/video.mp4 -s https://example.com/subtitle.srt -o subtitle_aligned.srt</code></pre>
200+
<pre><code>docker run -it baxtree/subaligner subaligner -m dual -v https://example.com/video.mp4 -s https://example.com/subtitle.srt -o subtitle_aligned.srt</code></pre>
201+
</details>
202+
203+
![](figures/screencast.gif)
204+
181205
The aligned subtitle will be saved at `subtitle_aligned.srt`. To obtain the subtitle in raw JSON format for downstream
182206
processing, replace the output file extension with `.json`. For details on CLIs, run `subaligner -h` or `subaligner_batch -h`,
183207
`subaligner_convert -h`, `subaligner_train -h` and `subaligner_tune -h` for additional utilities. `subaligner_1pass` and `subaligner_2pass` are shortcuts for running `subaligner` with `-m single` and `-m dual` options, respectively.
184208

185-
![](figures/screencast.gif)
186-
187209
## Advanced Usage
188-
You can train a new model with your own audiovisual files and subtitle files:
189-
```
190-
$ subaligner_train -vd VIDEO_DIRECTORY -sd SUBTITLE_DIRECTORY -tod TRAINING_OUTPUT_DIRECTORY
191-
```
210+
You can train a new model with your own audiovisual files and subtitle files,
211+
<details>
212+
<summary>Train a custom model</summary>
213+
<pre><code>subaligner_train -vd VIDEO_DIRECTORY -sd SUBTITLE_DIRECTORY -tod TRAINING_OUTPUT_DIRECTORY</code></pre>
214+
</details>
215+
192216
Then you can apply it to your subtitle synchronisation with the aforementioned commands. For more details on how to train and tune your own model, please refer to [Subaligner Docs](https://subaligner.readthedocs.io/en/latest/advanced_usage.html).
193217

194-
For larger media files taking longer to process, you can reconfigure various timeouts using the following options:
195-
```
196-
-mpt [Maximum waiting time in seconds when processing media files]
197-
-sat [Maximum waiting time in seconds when aligning each segment]
198-
-fet [Maximum waiting time in seconds when embedding features for training]
199-
```
218+
For larger media files taking longer to process, you can reconfigure various timeouts using the following:
219+
<details>
220+
<summary>Options for tuning timeouts</summary>
221+
<ul>
222+
<li><code>-mpt</code> [Maximum waiting time in seconds when processing media files]</li>
223+
<li><code>-sat</code> [Maximum waiting time in seconds when aligning each segment]</li>
224+
<li><code>-fet</code> [Maximum waiting time in seconds when embedding features for training]</li>
225+
</ul>
226+
</details>
200227

201228
## Anatomy
202229
Subtitles can be out of sync with their companion audiovisual media files for a variety of causes including latency introduced by Speech-To-Text on live streams or calibration and rectification involving human intervention during post-production.

0 commit comments

Comments
 (0)