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.
Files changed (60) hide show
  1. vtt_transcribe_server-0.1.0/.gitignore +222 -0
  2. vtt_transcribe_server-0.1.0/LICENSE +28 -0
  3. vtt_transcribe_server-0.1.0/PKG-INFO +267 -0
  4. vtt_transcribe_server-0.1.0/README.md +226 -0
  5. vtt_transcribe_server-0.1.0/docs/CHANGELOG.md +19 -0
  6. vtt_transcribe_server-0.1.0/hatch_build.py +28 -0
  7. vtt_transcribe_server-0.1.0/pyproject.toml +98 -0
  8. vtt_transcribe_server-0.1.0/tests/__init__.py +1 -0
  9. vtt_transcribe_server-0.1.0/tests/conftest.py +97 -0
  10. vtt_transcribe_server-0.1.0/tests/test_api/__init__.py +1 -0
  11. vtt_transcribe_server-0.1.0/tests/test_api/test_access.py +252 -0
  12. vtt_transcribe_server-0.1.0/tests/test_api/test_admin.py +138 -0
  13. vtt_transcribe_server-0.1.0/tests/test_api/test_app.py +461 -0
  14. vtt_transcribe_server-0.1.0/tests/test_api/test_auth.py +795 -0
  15. vtt_transcribe_server-0.1.0/tests/test_api/test_diarization.py +69 -0
  16. vtt_transcribe_server-0.1.0/tests/test_api/test_error_handling.py +112 -0
  17. vtt_transcribe_server-0.1.0/tests/test_api/test_errors.py +35 -0
  18. vtt_transcribe_server-0.1.0/tests/test_api/test_oauth.py +411 -0
  19. vtt_transcribe_server-0.1.0/tests/test_api/test_profile.py +236 -0
  20. vtt_transcribe_server-0.1.0/tests/test_api/test_queue.py +500 -0
  21. vtt_transcribe_server-0.1.0/tests/test_api/test_speakers.py +299 -0
  22. vtt_transcribe_server-0.1.0/tests/test_api/test_static_ui.py +48 -0
  23. vtt_transcribe_server-0.1.0/tests/test_api/test_transcription_endpoints.py +850 -0
  24. vtt_transcribe_server-0.1.0/tests/test_api/test_user_management.py +558 -0
  25. vtt_transcribe_server-0.1.0/tests/test_api/test_websockets.py +980 -0
  26. vtt_transcribe_server-0.1.0/tests/test_docker_compose.py +270 -0
  27. vtt_transcribe_server-0.1.0/tests/test_generate_secrets.py +278 -0
  28. vtt_transcribe_server-0.1.0/tests/test_packaging.py +177 -0
  29. vtt_transcribe_server-0.1.0/vtt_server/README.md +174 -0
  30. vtt_transcribe_server-0.1.0/vtt_server/__init__.py +5 -0
  31. vtt_transcribe_server-0.1.0/vtt_server/_version.py +8 -0
  32. vtt_transcribe_server-0.1.0/vtt_server/access.py +122 -0
  33. vtt_transcribe_server-0.1.0/vtt_server/app.py +158 -0
  34. vtt_transcribe_server-0.1.0/vtt_server/auth.py +185 -0
  35. vtt_transcribe_server-0.1.0/vtt_server/cli.py +179 -0
  36. vtt_transcribe_server-0.1.0/vtt_server/database.py +114 -0
  37. vtt_transcribe_server-0.1.0/vtt_server/engines.py +107 -0
  38. vtt_transcribe_server-0.1.0/vtt_server/errors.py +45 -0
  39. vtt_transcribe_server-0.1.0/vtt_server/jobqueue.py +220 -0
  40. vtt_transcribe_server-0.1.0/vtt_server/jobstore.py +136 -0
  41. vtt_transcribe_server-0.1.0/vtt_server/mailer.py +193 -0
  42. vtt_transcribe_server-0.1.0/vtt_server/manage.py +46 -0
  43. vtt_transcribe_server-0.1.0/vtt_server/models.py +98 -0
  44. vtt_transcribe_server-0.1.0/vtt_server/retention.py +129 -0
  45. vtt_transcribe_server-0.1.0/vtt_server/routes/__init__.py +1 -0
  46. vtt_transcribe_server-0.1.0/vtt_server/routes/admin.py +225 -0
  47. vtt_transcribe_server-0.1.0/vtt_server/routes/api_keys.py +172 -0
  48. vtt_transcribe_server-0.1.0/vtt_server/routes/auth.py +171 -0
  49. vtt_transcribe_server-0.1.0/vtt_server/routes/health.py +19 -0
  50. vtt_transcribe_server-0.1.0/vtt_server/routes/jobs.py +136 -0
  51. vtt_transcribe_server-0.1.0/vtt_server/routes/oauth.py +317 -0
  52. vtt_transcribe_server-0.1.0/vtt_server/routes/profile.py +182 -0
  53. vtt_transcribe_server-0.1.0/vtt_server/routes/speakers.py +239 -0
  54. vtt_transcribe_server-0.1.0/vtt_server/routes/transcription.py +894 -0
  55. vtt_transcribe_server-0.1.0/vtt_server/routes/websockets.py +185 -0
  56. vtt_transcribe_server-0.1.0/vtt_server/server.py +17 -0
  57. vtt_transcribe_server-0.1.0/vtt_server/static/assets/index-C6Q787Qu.js +7 -0
  58. vtt_transcribe_server-0.1.0/vtt_server/static/assets/index-CKsx-844.css +1 -0
  59. vtt_transcribe_server-0.1.0/vtt_server/static/favicon.svg +1 -0
  60. 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.