vtt-transcribe-server 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- vtt_transcribe_server-0.1.0/.gitignore +222 -0
- vtt_transcribe_server-0.1.0/LICENSE +28 -0
- vtt_transcribe_server-0.1.0/PKG-INFO +267 -0
- vtt_transcribe_server-0.1.0/README.md +226 -0
- vtt_transcribe_server-0.1.0/docs/CHANGELOG.md +19 -0
- vtt_transcribe_server-0.1.0/hatch_build.py +28 -0
- vtt_transcribe_server-0.1.0/pyproject.toml +98 -0
- vtt_transcribe_server-0.1.0/tests/__init__.py +1 -0
- vtt_transcribe_server-0.1.0/tests/conftest.py +97 -0
- vtt_transcribe_server-0.1.0/tests/test_api/__init__.py +1 -0
- vtt_transcribe_server-0.1.0/tests/test_api/test_access.py +252 -0
- vtt_transcribe_server-0.1.0/tests/test_api/test_admin.py +138 -0
- vtt_transcribe_server-0.1.0/tests/test_api/test_app.py +461 -0
- vtt_transcribe_server-0.1.0/tests/test_api/test_auth.py +795 -0
- vtt_transcribe_server-0.1.0/tests/test_api/test_diarization.py +69 -0
- vtt_transcribe_server-0.1.0/tests/test_api/test_error_handling.py +112 -0
- vtt_transcribe_server-0.1.0/tests/test_api/test_errors.py +35 -0
- vtt_transcribe_server-0.1.0/tests/test_api/test_oauth.py +411 -0
- vtt_transcribe_server-0.1.0/tests/test_api/test_profile.py +236 -0
- vtt_transcribe_server-0.1.0/tests/test_api/test_queue.py +500 -0
- vtt_transcribe_server-0.1.0/tests/test_api/test_speakers.py +299 -0
- vtt_transcribe_server-0.1.0/tests/test_api/test_static_ui.py +48 -0
- vtt_transcribe_server-0.1.0/tests/test_api/test_transcription_endpoints.py +850 -0
- vtt_transcribe_server-0.1.0/tests/test_api/test_user_management.py +558 -0
- vtt_transcribe_server-0.1.0/tests/test_api/test_websockets.py +980 -0
- vtt_transcribe_server-0.1.0/tests/test_docker_compose.py +270 -0
- vtt_transcribe_server-0.1.0/tests/test_generate_secrets.py +278 -0
- vtt_transcribe_server-0.1.0/tests/test_packaging.py +177 -0
- vtt_transcribe_server-0.1.0/vtt_server/README.md +174 -0
- vtt_transcribe_server-0.1.0/vtt_server/__init__.py +5 -0
- vtt_transcribe_server-0.1.0/vtt_server/_version.py +8 -0
- vtt_transcribe_server-0.1.0/vtt_server/access.py +122 -0
- vtt_transcribe_server-0.1.0/vtt_server/app.py +158 -0
- vtt_transcribe_server-0.1.0/vtt_server/auth.py +185 -0
- vtt_transcribe_server-0.1.0/vtt_server/cli.py +179 -0
- vtt_transcribe_server-0.1.0/vtt_server/database.py +114 -0
- vtt_transcribe_server-0.1.0/vtt_server/engines.py +107 -0
- vtt_transcribe_server-0.1.0/vtt_server/errors.py +45 -0
- vtt_transcribe_server-0.1.0/vtt_server/jobqueue.py +220 -0
- vtt_transcribe_server-0.1.0/vtt_server/jobstore.py +136 -0
- vtt_transcribe_server-0.1.0/vtt_server/mailer.py +193 -0
- vtt_transcribe_server-0.1.0/vtt_server/manage.py +46 -0
- vtt_transcribe_server-0.1.0/vtt_server/models.py +98 -0
- vtt_transcribe_server-0.1.0/vtt_server/retention.py +129 -0
- vtt_transcribe_server-0.1.0/vtt_server/routes/__init__.py +1 -0
- vtt_transcribe_server-0.1.0/vtt_server/routes/admin.py +225 -0
- vtt_transcribe_server-0.1.0/vtt_server/routes/api_keys.py +172 -0
- vtt_transcribe_server-0.1.0/vtt_server/routes/auth.py +171 -0
- vtt_transcribe_server-0.1.0/vtt_server/routes/health.py +19 -0
- vtt_transcribe_server-0.1.0/vtt_server/routes/jobs.py +136 -0
- vtt_transcribe_server-0.1.0/vtt_server/routes/oauth.py +317 -0
- vtt_transcribe_server-0.1.0/vtt_server/routes/profile.py +182 -0
- vtt_transcribe_server-0.1.0/vtt_server/routes/speakers.py +239 -0
- vtt_transcribe_server-0.1.0/vtt_server/routes/transcription.py +894 -0
- vtt_transcribe_server-0.1.0/vtt_server/routes/websockets.py +185 -0
- vtt_transcribe_server-0.1.0/vtt_server/server.py +17 -0
- vtt_transcribe_server-0.1.0/vtt_server/static/assets/index-C6Q787Qu.js +7 -0
- vtt_transcribe_server-0.1.0/vtt_server/static/assets/index-CKsx-844.css +1 -0
- vtt_transcribe_server-0.1.0/vtt_server/static/favicon.svg +1 -0
- vtt_transcribe_server-0.1.0/vtt_server/static/index.html +18 -0
|
@@ -0,0 +1,222 @@
|
|
|
1
|
+
# Custom
|
|
2
|
+
*.mp3
|
|
3
|
+
!/tests/*.mp3
|
|
4
|
+
*.ogg
|
|
5
|
+
*.wav
|
|
6
|
+
*.m4a
|
|
7
|
+
*.mp4
|
|
8
|
+
!/tests/*.mp4
|
|
9
|
+
*.txt
|
|
10
|
+
|
|
11
|
+
.copilot-worktrees/
|
|
12
|
+
|
|
13
|
+
# Byte-compiled / optimized / DLL files
|
|
14
|
+
__pycache__/
|
|
15
|
+
*.py[codz]
|
|
16
|
+
*$py.class
|
|
17
|
+
|
|
18
|
+
# C extensions
|
|
19
|
+
*.so
|
|
20
|
+
|
|
21
|
+
# Distribution / packaging
|
|
22
|
+
.Python
|
|
23
|
+
build/
|
|
24
|
+
develop-eggs/
|
|
25
|
+
dist/
|
|
26
|
+
downloads/
|
|
27
|
+
eggs/
|
|
28
|
+
.eggs/
|
|
29
|
+
lib/
|
|
30
|
+
lib64/
|
|
31
|
+
parts/
|
|
32
|
+
sdist/
|
|
33
|
+
var/
|
|
34
|
+
wheels/
|
|
35
|
+
share/python-wheels/
|
|
36
|
+
*.egg-info/
|
|
37
|
+
.installed.cfg
|
|
38
|
+
*.egg
|
|
39
|
+
MANIFEST
|
|
40
|
+
|
|
41
|
+
# PyInstaller
|
|
42
|
+
# Usually these files are written by a python script from a template
|
|
43
|
+
# before PyInstaller builds the exe, so as to inject date/other infos into it.
|
|
44
|
+
*.manifest
|
|
45
|
+
*.spec
|
|
46
|
+
|
|
47
|
+
# Installer logs
|
|
48
|
+
pip-log.txt
|
|
49
|
+
pip-delete-this-directory.txt
|
|
50
|
+
|
|
51
|
+
# Unit test / coverage reports
|
|
52
|
+
htmlcov/
|
|
53
|
+
.tox/
|
|
54
|
+
.nox/
|
|
55
|
+
.coverage
|
|
56
|
+
.coverage.*
|
|
57
|
+
.cache
|
|
58
|
+
nosetests.xml
|
|
59
|
+
coverage.xml
|
|
60
|
+
*.cover
|
|
61
|
+
*.py.cover
|
|
62
|
+
.hypothesis/
|
|
63
|
+
.pytest_cache/
|
|
64
|
+
cover/
|
|
65
|
+
|
|
66
|
+
# Translations
|
|
67
|
+
*.mo
|
|
68
|
+
*.pot
|
|
69
|
+
|
|
70
|
+
# Django stuff:
|
|
71
|
+
*.log
|
|
72
|
+
local_settings.py
|
|
73
|
+
db.sqlite3
|
|
74
|
+
db.sqlite3-journal
|
|
75
|
+
|
|
76
|
+
# Flask stuff:
|
|
77
|
+
instance/
|
|
78
|
+
.webassets-cache
|
|
79
|
+
|
|
80
|
+
# Scrapy stuff:
|
|
81
|
+
.scrapy
|
|
82
|
+
|
|
83
|
+
# Sphinx documentation
|
|
84
|
+
docs/_build/
|
|
85
|
+
|
|
86
|
+
# PyBuilder
|
|
87
|
+
.pybuilder/
|
|
88
|
+
target/
|
|
89
|
+
|
|
90
|
+
# Jupyter Notebook
|
|
91
|
+
.ipynb_checkpoints
|
|
92
|
+
|
|
93
|
+
# IPython
|
|
94
|
+
profile_default/
|
|
95
|
+
ipython_config.py
|
|
96
|
+
|
|
97
|
+
# pyenv
|
|
98
|
+
# For a library or package, you might want to ignore these files since the code is
|
|
99
|
+
# intended to run in multiple environments; otherwise, check them in:
|
|
100
|
+
# .python-version
|
|
101
|
+
|
|
102
|
+
# pipenv
|
|
103
|
+
# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
|
|
104
|
+
# However, in case of collaboration, if having platform-specific dependencies or dependencies
|
|
105
|
+
# having no cross-platform support, pipenv may install dependencies that don't work, or not
|
|
106
|
+
# install all needed dependencies.
|
|
107
|
+
#Pipfile.lock
|
|
108
|
+
|
|
109
|
+
# UV
|
|
110
|
+
# Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
|
|
111
|
+
# This is especially recommended for binary packages to ensure reproducibility, and is more
|
|
112
|
+
# commonly ignored for libraries.
|
|
113
|
+
#uv.lock
|
|
114
|
+
|
|
115
|
+
# poetry
|
|
116
|
+
# Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
|
|
117
|
+
# This is especially recommended for binary packages to ensure reproducibility, and is more
|
|
118
|
+
# commonly ignored for libraries.
|
|
119
|
+
# https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
|
|
120
|
+
#poetry.lock
|
|
121
|
+
#poetry.toml
|
|
122
|
+
|
|
123
|
+
# pdm
|
|
124
|
+
# Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
|
|
125
|
+
# pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
|
|
126
|
+
# https://pdm-project.org/en/latest/usage/project/#working-with-version-control
|
|
127
|
+
#pdm.lock
|
|
128
|
+
#pdm.toml
|
|
129
|
+
.pdm-python
|
|
130
|
+
.pdm-build/
|
|
131
|
+
|
|
132
|
+
# pixi
|
|
133
|
+
# Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
|
|
134
|
+
#pixi.lock
|
|
135
|
+
# Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
|
|
136
|
+
# in the .venv directory. It is recommended not to include this directory in version control.
|
|
137
|
+
.pixi
|
|
138
|
+
|
|
139
|
+
# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
|
|
140
|
+
__pypackages__/
|
|
141
|
+
|
|
142
|
+
# Celery stuff
|
|
143
|
+
celerybeat-schedule
|
|
144
|
+
celerybeat.pid
|
|
145
|
+
|
|
146
|
+
# SageMath parsed files
|
|
147
|
+
*.sage.py
|
|
148
|
+
|
|
149
|
+
# Environments
|
|
150
|
+
.env
|
|
151
|
+
.envrc
|
|
152
|
+
.venv
|
|
153
|
+
env/
|
|
154
|
+
venv/
|
|
155
|
+
ENV/
|
|
156
|
+
env.bak/
|
|
157
|
+
venv.bak/
|
|
158
|
+
|
|
159
|
+
# Spyder project settings
|
|
160
|
+
.spyderproject
|
|
161
|
+
.spyproject
|
|
162
|
+
|
|
163
|
+
# Rope project settings
|
|
164
|
+
.ropeproject
|
|
165
|
+
|
|
166
|
+
# mkdocs documentation
|
|
167
|
+
/site
|
|
168
|
+
|
|
169
|
+
# mypy
|
|
170
|
+
.mypy_cache/
|
|
171
|
+
.dmypy.json
|
|
172
|
+
dmypy.json
|
|
173
|
+
|
|
174
|
+
# Pyre type checker
|
|
175
|
+
.pyre/
|
|
176
|
+
|
|
177
|
+
# pytype static type analyzer
|
|
178
|
+
.pytype/
|
|
179
|
+
|
|
180
|
+
# Cython debug symbols
|
|
181
|
+
cython_debug/
|
|
182
|
+
|
|
183
|
+
# PyCharm
|
|
184
|
+
# JetBrains specific template is maintained in a separate JetBrains.gitignore that can
|
|
185
|
+
# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
|
|
186
|
+
# and can be added to the global gitignore or merged into this file. For a more nuclear
|
|
187
|
+
# option (not recommended) you can uncomment the following to ignore the entire idea folder.
|
|
188
|
+
#.idea/
|
|
189
|
+
|
|
190
|
+
# Abstra
|
|
191
|
+
# Abstra is an AI-powered process automation framework.
|
|
192
|
+
# Ignore directories containing user credentials, local state, and settings.
|
|
193
|
+
# Learn more at https://abstra.io/docs
|
|
194
|
+
.abstra/
|
|
195
|
+
|
|
196
|
+
# Visual Studio Code
|
|
197
|
+
# Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
|
|
198
|
+
# that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
|
|
199
|
+
# and can be added to the global gitignore or merged into this file. However, if you prefer,
|
|
200
|
+
# you could uncomment the following to ignore the entire vscode folder
|
|
201
|
+
# .vscode/
|
|
202
|
+
|
|
203
|
+
# Ruff stuff:
|
|
204
|
+
.ruff_cache/
|
|
205
|
+
|
|
206
|
+
# PyPI configuration file
|
|
207
|
+
.pypirc
|
|
208
|
+
|
|
209
|
+
# Cursor
|
|
210
|
+
# Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
|
|
211
|
+
# exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
|
|
212
|
+
# refer to https://docs.cursor.com/context/ignore-files
|
|
213
|
+
.cursorignore
|
|
214
|
+
.cursorindexingignore
|
|
215
|
+
|
|
216
|
+
# Marimo
|
|
217
|
+
marimo/_static/
|
|
218
|
+
marimo/_lsp/
|
|
219
|
+
__marimo__/
|
|
220
|
+
.env
|
|
221
|
+
*.db
|
|
222
|
+
vtt_server/static/
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
BSD 3-Clause License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026, JLCodeSource
|
|
4
|
+
|
|
5
|
+
Redistribution and use in source and binary forms, with or without
|
|
6
|
+
modification, are permitted provided that the following conditions are met:
|
|
7
|
+
|
|
8
|
+
1. Redistributions of source code must retain the above copyright notice, this
|
|
9
|
+
list of conditions and the following disclaimer.
|
|
10
|
+
|
|
11
|
+
2. Redistributions in binary form must reproduce the above copyright notice,
|
|
12
|
+
this list of conditions and the following disclaimer in the documentation
|
|
13
|
+
and/or other materials provided with the distribution.
|
|
14
|
+
|
|
15
|
+
3. Neither the name of the copyright holder nor the names of its
|
|
16
|
+
contributors may be used to endorse or promote products derived from
|
|
17
|
+
this software without specific prior written permission.
|
|
18
|
+
|
|
19
|
+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
|
20
|
+
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
21
|
+
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
|
22
|
+
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
|
|
23
|
+
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
24
|
+
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
|
|
25
|
+
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
|
|
26
|
+
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
|
|
27
|
+
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
|
28
|
+
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
@@ -0,0 +1,267 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: vtt-transcribe-server
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: FastAPI server (users, OAuth, DB, job API) and web app built on the vtt-transcribe transcription package
|
|
5
|
+
Project-URL: Homepage, https://github.com/JLCodeSource/vtt-transcribe-server
|
|
6
|
+
Project-URL: Repository, https://github.com/JLCodeSource/vtt-transcribe-server
|
|
7
|
+
Project-URL: Issues, https://github.com/JLCodeSource/vtt-transcribe-server/issues
|
|
8
|
+
Project-URL: Changelog, https://github.com/JLCodeSource/vtt-transcribe-server/blob/main/docs/CHANGELOG.md
|
|
9
|
+
Author-email: JLCodeSource <JLCodeSource@gmail.com>
|
|
10
|
+
License: BSD-3-Clause
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Keywords: diarization,fastapi,speech-to-text,subtitles,transcription,whisper
|
|
13
|
+
Classifier: Development Status :: 4 - Beta
|
|
14
|
+
Classifier: Framework :: FastAPI
|
|
15
|
+
Classifier: Intended Audience :: End Users/Desktop
|
|
16
|
+
Classifier: License :: OSI Approved :: BSD License
|
|
17
|
+
Classifier: Programming Language :: Python :: 3
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
21
|
+
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
|
|
22
|
+
Requires-Python: >=3.11
|
|
23
|
+
Requires-Dist: aiosqlite>=0.19.0
|
|
24
|
+
Requires-Dist: asyncpg>=0.29.0
|
|
25
|
+
Requires-Dist: authlib>=1.3.0
|
|
26
|
+
Requires-Dist: bcrypt<5.0.0,>=4.0.0
|
|
27
|
+
Requires-Dist: cryptography>=41.0.0
|
|
28
|
+
Requires-Dist: email-validator>=2.0.0
|
|
29
|
+
Requires-Dist: fastapi>=0.115.0
|
|
30
|
+
Requires-Dist: httpx>=0.27.0
|
|
31
|
+
Requires-Dist: itsdangerous>=2.1.0
|
|
32
|
+
Requires-Dist: passlib[bcrypt]>=1.7.4
|
|
33
|
+
Requires-Dist: pyjwt>=2.10.0
|
|
34
|
+
Requires-Dist: python-multipart>=0.0.20
|
|
35
|
+
Requires-Dist: sqlalchemy[asyncio]>=2.0.0
|
|
36
|
+
Requires-Dist: uvicorn[standard]>=0.34.0
|
|
37
|
+
Requires-Dist: vtt-transcribe[sherpa]>=0.6.2
|
|
38
|
+
Provides-Extra: local
|
|
39
|
+
Requires-Dist: vtt-transcribe[local]>=0.6.2; extra == 'local'
|
|
40
|
+
Description-Content-Type: text/markdown
|
|
41
|
+
|
|
42
|
+
# vtt-transcribe-server
|
|
43
|
+
|
|
44
|
+
Server side of **vtt-transcribe**: FastAPI API (`vtt_server/`), users / OAuth / DB, the Svelte 5 web
|
|
45
|
+
app (`frontend/`), and Docker / docker-compose deployment.
|
|
46
|
+
|
|
47
|
+
This repo was extracted (with full git history) from
|
|
48
|
+
[JLCodeSource/vtt-transcribe](https://github.com/JLCodeSource/vtt-transcribe).
|
|
49
|
+
|
|
50
|
+
## Install and run
|
|
51
|
+
|
|
52
|
+
Pick one. All three serve the web app and the API from one address; sign up in the browser to create the first account.
|
|
53
|
+
|
|
54
|
+
### With pip (Python 3.11+)
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
pip install vtt-transcribe-server # OpenAI Whisper (needs an API key) + key-free speaker identification
|
|
58
|
+
pip install "vtt-transcribe-server[local]" # adds key-free on-box Whisper and translation (large: faster-whisper)
|
|
59
|
+
|
|
60
|
+
vtt-server init # writes ./.env with freshly generated SECRET_KEY, ENCRYPTION_KEY and SESSION_SECRET
|
|
61
|
+
vtt-server # http://127.0.0.1:8000
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
`vtt-server` keeps its database, uploads and models under `~/.local/share/vtt-transcribe-server` (`--data-dir` changes it).
|
|
65
|
+
Options: `--host` (use `0.0.0.0` to expose it), `--port`, `--database-url` (SQLite by default; `postgresql://user:pass@host/db`
|
|
66
|
+
works too), `--env-file`. Settings come from the environment and from `./.env`; see the environment table below. The server
|
|
67
|
+
will not start without `SECRET_KEY` and `ENCRYPTION_KEY`; it never falls back to built-in secrets. You also need `ffmpeg` on
|
|
68
|
+
the `PATH` for real transcription (`apt install ffmpeg`, `brew install ffmpeg`). Run **one** server process.
|
|
69
|
+
|
|
70
|
+
### With Docker
|
|
71
|
+
|
|
72
|
+
```bash
|
|
73
|
+
docker run -d --name vtt -p 8000:8000 --env-file .env -v vtt-data:/app/jobs -v vtt-models:/app/models \
|
|
74
|
+
-e DATABASE_URL=sqlite+aiosqlite:////app/jobs/vtt.db \
|
|
75
|
+
ghcr.io/jlcodesource/vtt-transcribe-server:latest
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
`.env` needs `SECRET_KEY` and `ENCRYPTION_KEY`; create it with `pip install vtt-transcribe-server && vtt-server init`, or with
|
|
79
|
+
`python scripts/generate_secrets.py` from a checkout. Tags: `latest` / `<version>` (lean, OpenAI engine) and `local` /
|
|
80
|
+
`<version>-local` (adds the key-free engine, about twice the size). The images are `linux/amd64` only; on arm64 (Apple silicon,
|
|
81
|
+
Raspberry Pi) build your own: `docker build --target api-ui -t vtt-server .`.
|
|
82
|
+
|
|
83
|
+
### With docker compose (PostgreSQL + the app + a local mail relay)
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
git clone https://github.com/JLCodeSource/vtt-transcribe-server && cd vtt-transcribe-server
|
|
87
|
+
cp .env.example .env && python3 scripts/generate_secrets.py # then fill in POSTGRES_PASSWORD and the secrets
|
|
88
|
+
docker compose --profile frontend up -d --build
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
Details: [docs/DOCKER_COMPOSE.md](docs/DOCKER_COMPOSE.md).
|
|
92
|
+
|
|
93
|
+
### Upgrade
|
|
94
|
+
|
|
95
|
+
```bash
|
|
96
|
+
pip install --upgrade vtt-transcribe-server # then restart vtt-server
|
|
97
|
+
docker pull ghcr.io/jlcodesource/vtt-transcribe-server:latest # then recreate the container
|
|
98
|
+
git pull && docker compose --profile frontend up -d --build # compose
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
New database columns are added automatically at startup; keep the same `ENCRYPTION_KEY` (it protects stored API keys).
|
|
102
|
+
Release notes: [docs/CHANGELOG.md](docs/CHANGELOG.md).
|
|
103
|
+
|
|
104
|
+
## Three-repo layout
|
|
105
|
+
|
|
106
|
+
| Repo | Visibility | Contents |
|
|
107
|
+
|------|-----------|----------|
|
|
108
|
+
| `vtt-transcribe` | public | Python CLI/library: Whisper transcription, chunking, diarization, translator. Published to PyPI + Docker Hub. |
|
|
109
|
+
| `vtt-transcribe-server` (this repo) | public | FastAPI API, users/OAuth/DB, Svelte web app, Docker/compose. **Depends on** `vtt-transcribe`. |
|
|
110
|
+
| `vtt-transcribe-web` | public | Separate static (BYOK/WASM) web app. |
|
|
111
|
+
|
|
112
|
+
The dependency is one-way: the server imports `VideoTranscriber`, `AudioTranslator`, `get_logger` and
|
|
113
|
+
`__version__` from `vtt_transcribe`; the core never imports the server.
|
|
114
|
+
|
|
115
|
+
The server package is named **`vtt_server`** (it used to be `vtt_transcribe.api`). A regular package named
|
|
116
|
+
`vtt_transcribe` cannot share its namespace with the installed core, hence the rename.
|
|
117
|
+
|
|
118
|
+
## How the core is consumed
|
|
119
|
+
|
|
120
|
+
`vtt-transcribe[sherpa]>=0.6.2` from PyPI (transcription, translation, shared speaker logic, and the key-free sherpa-onnx
|
|
121
|
+
diarizer: CPU, no torch, no token). Optional extra `local` adds key-free on-box Whisper and translation
|
|
122
|
+
(`uv sync --extra local`). pyannote/torch was dropped to keep the install and image small.
|
|
123
|
+
See [docs/DESIGN.md](docs/DESIGN.md) for the target API, job model and deployment plan.
|
|
124
|
+
|
|
125
|
+
## Develop
|
|
126
|
+
|
|
127
|
+
Requirements: Python >=3.11, [uv](https://docs.astral.sh/uv/), ffmpeg (for real transcription).
|
|
128
|
+
|
|
129
|
+
```bash
|
|
130
|
+
uv sync # server + dev deps + key-free speaker diarization
|
|
131
|
+
cp .env.example .env
|
|
132
|
+
uv run python scripts/generate_secrets.py # fill SECRET_KEY / ENCRYPTION_KEY / SESSION_SECRET in .env
|
|
133
|
+
uv run vtt-server # server on 127.0.0.1:8000 (docs at /docs); the API only, unless the UI is built:
|
|
134
|
+
sh scripts/build_ui.sh # (Node 22+) builds the web app into vtt_server/static, which the server then serves
|
|
135
|
+
cd frontend && npm run dev # or: live-reloading frontend on :5173, proxying /api to :8000
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
Full stack (Postgres + API, `--profile frontend` adds the web app): see
|
|
139
|
+
[docs/DOCKER_COMPOSE.md](docs/DOCKER_COMPOSE.md).
|
|
140
|
+
|
|
141
|
+
```bash
|
|
142
|
+
docker compose up -d --build
|
|
143
|
+
docker compose --profile frontend up -d --build
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
The `Dockerfile` has two targets (~530 MB each, or ~930 MB with `--build-arg SYNC_ARGS="--extra local"`; ffmpeg is the static binary from the venv, not the apt package):
|
|
147
|
+
|
|
148
|
+
```bash
|
|
149
|
+
docker build --target api -t vtt-server . # API only; the frontend ships as its own nginx image (frontend/Dockerfile)
|
|
150
|
+
docker build --target api-ui -t vtt-server-ui . # API + built frontend served at / (single container)
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
The frontend always calls relative `/api/...`, so it works unchanged behind nginx, behind the API, or via the Vite dev proxy.
|
|
154
|
+
|
|
155
|
+
## Tests and lint
|
|
156
|
+
|
|
157
|
+
```bash
|
|
158
|
+
uv run pytest # backend (tests/test_api, docker-compose, generate_secrets)
|
|
159
|
+
uv run ruff check .
|
|
160
|
+
cd frontend && npm ci && npm run test # frontend unit tests (Vitest)
|
|
161
|
+
cd frontend && npm run test:e2e # Playwright E2E (needs the backend running)
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
No make/uv/node on the host? Use containers:
|
|
165
|
+
|
|
166
|
+
```bash
|
|
167
|
+
docker run --rm -v "$PWD":/w -w /w -e UV_PROJECT_ENVIRONMENT=/opt/venv python:3.12-slim bash -c \
|
|
168
|
+
'pip install -q uv && uv sync --frozen && /opt/venv/bin/pytest -q -p no:cacheprovider && /opt/venv/bin/ruff check .'
|
|
169
|
+
docker run --rm -v "$PWD/frontend":/w -w /w node:22-slim bash -c 'npm ci && npm run test'
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
## CI
|
|
173
|
+
|
|
174
|
+
Four workflows. The first three are path-filtered, with superseded runs cancelled and a timeout on every job:
|
|
175
|
+
|
|
176
|
+
| Workflow | Runs when | Does |
|
|
177
|
+
|---|---|---|
|
|
178
|
+
| `ci.yml` | backend files change | `ruff check` and `pytest` (one job) |
|
|
179
|
+
| `docker-build-test.yml` | anything in the image changes | builds the lean image, checks it runs as non-root, starts and answers `/health`, serves the UI, protects `/api` |
|
|
180
|
+
| `frontend-ci.yml` | frontend or backend files change | Vitest unit tests; the browser end-to-end job is manual (`workflow_dispatch`) |
|
|
181
|
+
| `release.yml` | a `v*` tag is pushed, or by hand (dry run by default) | builds the UI and the package, tests the wheel in a clean venv, publishes to TestPyPI then PyPI (trusted publishing, reviewer-gated environments), pushes the GHCR images, creates the GitHub release |
|
|
182
|
+
|
|
183
|
+
The repo is public, so standard-runner minutes are free, but run the checks above locally first: CI is a safety net, not the
|
|
184
|
+
first line of testing. Only `release.yml` publishes anything.
|
|
185
|
+
|
|
186
|
+
### Releasing
|
|
187
|
+
|
|
188
|
+
Bump `version` in `pyproject.toml`, add a section for it to `docs/CHANGELOG.md`, merge, then `git tag vX.Y.Z && git push origin vX.Y.Z`.
|
|
189
|
+
The workflow stops at the `testpypi` and `pypi` environments until a reviewer approves them. One-time setup: create those two
|
|
190
|
+
environments, and register a PyPI and a TestPyPI *pending publisher* for `vtt-transcribe-server` (owner `JLCodeSource`,
|
|
191
|
+
repository `vtt-transcribe-server`, workflow `release.yml`, environment `testpypi` / `pypi`). To rehearse without publishing,
|
|
192
|
+
run the workflow manually from the Actions tab and leave `dry_run` ticked. Building the package locally:
|
|
193
|
+
|
|
194
|
+
```bash
|
|
195
|
+
docker run --rm -v "$PWD":/w -w /w node:22-slim sh scripts/build_ui.sh # web UI into vtt_server/static
|
|
196
|
+
docker run --rm -v "$PWD":/w -w /w python:3.12-slim bash -c 'pip install -q uv && uv build' # dist/*.whl and *.tar.gz
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
## Job queue
|
|
200
|
+
|
|
201
|
+
Every upload joins a queue; one worker runs jobs strictly one at a time, in order. After submitting, the UI opens the **Jobs**
|
|
202
|
+
page, which shows each job's queue position and, while it runs, its step (detecting language, transcribing, identifying
|
|
203
|
+
speakers, translating) and a progress percentage. Waiting jobs can be cancelled; a running job stops at its next checkpoint.
|
|
204
|
+
Jobs, results and uploaded audio are stored (database + `VTT_DATA_DIR`), so the queue and finished transcripts survive a
|
|
205
|
+
restart; anything that was waiting or running is re-queued on startup. Run **one** API process: the queue lives inside it.
|
|
206
|
+
|
|
207
|
+
Results stay downloadable and reviewable until their retention runs out (see the table below). Each user sets a default
|
|
208
|
+
under **Profile**, can override it per file and later per job; the Jobs page shows the expiry date. The Profile page also holds
|
|
209
|
+
your OpenAI key (stored encrypted, shown only as its last four characters, used when a request has none), the email opt-out,
|
|
210
|
+
password change and account deletion. Email is optional (compose runs a local Postfix relay for it): with `SMTP_HOST` set, new users get a welcome email and job owners
|
|
211
|
+
get a "ready / failed" email linking to the job unless they opt out. There is no email verification step.
|
|
212
|
+
|
|
213
|
+
## Security
|
|
214
|
+
|
|
215
|
+
Every `/api` endpoint and the job WebSocket require a signed-in, active user, and each job belongs to the user who
|
|
216
|
+
created it (others get `404`; administrators can see all). A user whose password an administrator has reset must change it
|
|
217
|
+
before the API will serve them. Administrators manage users on the **Admin** page or under `/admin`
|
|
218
|
+
([docs/USER_MANAGEMENT.md](docs/USER_MANAGEMENT.md)).
|
|
219
|
+
|
|
220
|
+
Uploads are limited to 100 MB. Environment settings (all optional):
|
|
221
|
+
|
|
222
|
+
| Variable | Default | Effect |
|
|
223
|
+
|---|---|---|
|
|
224
|
+
| `VTT_ALLOW_REGISTRATION` | `true` | `false` closes self-service sign-up; create users another way and promote with `python -m vtt_server.manage` |
|
|
225
|
+
| `VTT_LOGIN_RATE_LIMIT` / `VTT_REGISTER_RATE_LIMIT` | `10` / `5` | attempts per client address per 5 minutes before `429` (`0` disables) |
|
|
226
|
+
| `VTT_MAX_ACTIVE_JOBS_PER_USER` | `10` | queued + running jobs per user before `429` (`0` disables) |
|
|
227
|
+
| `VTT_MAX_ACTIVE_JOBS` | `50` | queued + running jobs on the whole server before `503` (`0` disables) |
|
|
228
|
+
| `VTT_DATA_DIR` | system temp | where uploaded audio is stored; **use a persistent volume** so queued jobs survive a restart |
|
|
229
|
+
| `VTT_STATIC_DIR` | unset | folder with the built web app to serve at `/`. Unset: the copy packaged in the wheel (if present); empty: no web UI, API only |
|
|
230
|
+
| `VTT_SERVER_DATA_DIR` | `~/.local/share/vtt-transcribe-server` | `vtt-server` only: parent of the SQLite database, `jobs/` and `models/` (same as `--data-dir`) |
|
|
231
|
+
| `DATABASE_URL` | SQLite file (`vtt-server`: in the data dir) | `postgresql://user:pass@host/db` for PostgreSQL |
|
|
232
|
+
| `API_HOST` / `API_PORT` | `127.0.0.1` / `8000` | `vtt-server` listen address (`--host` / `--port`) |
|
|
233
|
+
| `VTT_DEFAULT_RETENTION_DAYS` | `7` | platform default: finished jobs are kept this many days (users can choose keep / delete / hold N days in their profile, per upload, or later on the job) |
|
|
234
|
+
| `VTT_DELETE_GRACE_MINUTES` / `VTT_DELETE_UNDOWNLOADED_HOURS` | `15` / `24` | policy "delete": removed 15 minutes after the first download, or 24 h after finishing if never downloaded |
|
|
235
|
+
| `VTT_SWEEP_INTERVAL_SECONDS` | `300` | how often expired jobs and their files are deleted |
|
|
236
|
+
| `VTT_PUBLIC_URL` | _(empty)_ | base URL used for links in emails (`<url>/?job=<id>`) |
|
|
237
|
+
| `SMTP_HOST` `SMTP_PORT` `SMTP_USER` `SMTP_PASSWORD` `SMTP_FROM` `SMTP_STARTTLS` | `mail` / `25` / … / `noreply@$VTT_MAIL_DOMAIN` / `false` (compose); empty outside compose | outgoing email (welcome message, "your job is ready"). Compose points these at the bundled `mail` relay; set `SMTP_HOST` to your own server instead, or empty to switch email off. Without `SMTP_HOST` nothing is sent and nothing fails. Port 465 uses implicit TLS |
|
|
238
|
+
| `VTT_MAIL_DOMAIN` `VTT_MAIL_HOSTNAME` `RELAYHOST` `RELAYHOST_USERNAME` `RELAYHOST_PASSWORD` | `localhost` / `mail.$VTT_MAIL_DOMAIN` / _(empty)_ | the bundled Postfix `mail` service (compose only, not published on the host): sender domain, its HELO name, and an optional smarthost to send through. With no `RELAYHOST` it delivers directly; without SPF/DKIM/reverse DNS for your domain such mail is often filtered as spam |
|
|
239
|
+
| `ENVIRONMENT` | `development` | set `production` only when served over HTTPS (it makes session cookies HTTPS-only) |
|
|
240
|
+
|
|
241
|
+
Before exposing an instance to the internet:
|
|
242
|
+
|
|
243
|
+
- **Serve it over HTTPS** (for example Caddy in front). Passwords and tokens are otherwise sent in clear text.
|
|
244
|
+
- Audio-clip and WebSocket URLs carry the token as `?access_token=` because browsers cannot set headers there; keep HTTPS on
|
|
245
|
+
and avoid logging query strings in your proxy.
|
|
246
|
+
- Generate real `SECRET_KEY`, `ENCRYPTION_KEY` and `SESSION_SECRET` values (`scripts/generate_secrets.py`) and never reuse the examples.
|
|
247
|
+
- Jobs and uploads are held on the server's disk and in memory; there is no automatic retention yet, so delete jobs you no longer
|
|
248
|
+
need and size the host for the local engines (`engine=local` wants 2 GB or more).
|
|
249
|
+
- Rate limits are per process and in memory, so they reset on restart and are not shared between replicas.
|
|
250
|
+
|
|
251
|
+
Report vulnerabilities privately through GitHub's "Report a vulnerability" (Security tab) rather than a public issue.
|
|
252
|
+
|
|
253
|
+
## Judgment calls in the extraction
|
|
254
|
+
|
|
255
|
+
- Dropped core-only: CLI/transcriber/chunker/diarization/handlers/formatter/translator modules, CLI tests and smoke
|
|
256
|
+
tests, sample media, `Dockerfile.diarization*` and the `cli` Docker target, PyPI/Docker-Hub/release/nox workflows,
|
|
257
|
+
release/PyPI/changelog/registry docs, `noxfile.py`, devcontainer, beads tracker, Copilot/AGENTS instructions,
|
|
258
|
+
pre-commit hooks, dependabot config.
|
|
259
|
+
- `docs/USER_SETUP_GUIDE.md` (despite the name, it is a PyPI-publishing guide) was **not** kept: it belongs to the core.
|
|
260
|
+
- Kept `docs/DOCKER_SETUP.md` (compose-based) alongside `docs/DOCKER_COMPOSE.md`.
|
|
261
|
+
- Server Python base image moved from 3.13 to 3.12-slim; `.python-version` is 3.12.
|
|
262
|
+
- `api` extra became normal dependencies; `dev`/`build` extras folded into the `dev` dependency group (the package is
|
|
263
|
+
published to PyPI by `release.yml`; `hatchling` is a dev dependency only for the packaging test).
|
|
264
|
+
- `/health` reports this package's `version` and, separately, the core's `core_version`.
|
|
265
|
+
- The Postgres DB/user names (`vtt_transcribe`, `vtt_user`) and the `vtt-transcribe-*` container names were left
|
|
266
|
+
unchanged to avoid breaking existing deployments/volumes.
|
|
267
|
+
- E2E (Playwright) tests were not run locally (need browsers); backend and frontend unit tests were.
|