Назначение и границы системы

Sub Video Manager ведёт проекты субтитров от обнаружения YouTube-ролика до публикации: метаданные, исходные субтитры, перевод, таймкоды, проверка, оформление, CapCut draft, серверные файлы и итоговые ссылки.

Desktop-клиент — основная рабочая поверхность. API — канонический слой общих данных и файлов. Локальные каталоги остаются рабочей копией пользователя. Большие видео хранятся отдельно от файлового синка.

Архитектура

Публичные адреса

• Основной API: https://api.xn--90a5ag.space/neuro-subs-api.
• Документация: https://api.xn--90a5ag.space/about.
• Media: отдельный домен из серверной настройки; ссылки подписаны и ограничены по времени.

Клиент использует единый production API. Публичный HTTPS завершается в Caddy, который передаёт запросы на локальный порт API.

Авторизация и права

После POST /auth/login клиент хранит случайный bearer token. На защищённых запросах передаётся Authorization: Bearer <token> и версия клиента в X-Neuro-Subs-Client-Version.

POST /neuro-subs-api/auth/login
Content-Type: application/json

{"login":"user","password":"…","device_id":"windows-host","client_version":"2.3.0"}

CapCut-привязка хранится отдельно для каждого логина. API не должен возвращать пользователю имена drafts других пользователей.

Тема интерфейса хранится только локально по нормализованному логину и версии схемы: тёмная, светлая или системная, восемь пресетов и собственный accent. Она не синхронизируется через account preferences; контрастный цвет текста вычисляется для каждого accent.

Модель проекта

Дата

Интерфейс принимает 24.12.2023, 2023-12-24, 24 дек 2023 и 24 дек. 2023 г.. В хранилище записывается 2023-12-24. Невалидная дата не должна тихо затирать существующее значение.

Типы контента

Типы не хранятся отдельным фиксированным списком. Канонический источник — коллекция content_type_rules: каждая запись связывает ключевую фразу заголовка с типом. Список типов выводится из уникальных значений правил и уже существующих проектов.

1. Заголовок нормализуется.
2. Проверяются правила keyword → content type.
3. При нескольких совпадениях побеждает более длинный keyword; затем более специфичный тип; затем более раннее правило.
4. Если совпадений нет, пользователь выбирает существующий тип или создаёт новое правило.
5. Выбранный тип записывается в проект и определяет локальную папку.

Все годовые варианты STAYweeK канонизируются в единый тип STAYweeK. STAYweek 2024, STAYweek 2025 и аналогичные папки считаются legacy.

Для интервью используются дополнительные поля источника и участников. Двуязычная очистка заголовка включается только у серий, где корейская и английская части систематически дублируют друг друга; произвольные скобки удалять нельзя.

Чекпойнты и статусы

published=true автоматически покрывает предыдущие обязательные этапы. Legacy stage мигрируется в checkpoints и больше не является источником истины.

Файлы и каталоги

Два представления одного проекта

• Локально: <content_type>/<unicode-safe-project-slug>/ — удобно человеку и CapCut.
• На сервере sync: projects/<project_id>/ — стабильно при переименовании или смене типа.
• Видео на сервере: отдельное video storage по типу/названию; оно не входит в обычный sync manifest.

Видео, .part, временные файлы, lock-файлы, cache, review frames и published output исключены из обычного sync. Это предотвращает тяжёлые случайные загрузки и конфликт рабочих артефактов.

Синхронизация

Синк сравнивает SHA-256, размер, mtime и серверную revision. Современная схема путей — project-id-v1. Клиент отображает серверный namespace через локальный mapping и никогда не должен хешировать исчезнувший файл без повторной проверки существования.

Цикл синка

1. Клиент сканирует локальный manifest и сопоставляет папки с project IDs.
2. POST /sync/manifest/diff возвращает upload/download/delete decisions и server cursor.
3. Мелкие наборы передаются batch ZIP. Большие файлы используют start → chunks → complete.
4. Каждая запись проверяется по path policy, размеру, SHA-256 и expected server revision.
5. Перед destructive изменением сервер создаёт backup; администратор может выполнить rollback.
6. Локальная state-база сохраняет последний server cursor и revisions.

Конфликт

Если обе стороны изменились после последней общей revision, клиент не должен молча выбирать файл. Для server-authoritative файлов требуется явное действие. Для текста показывается сводка изменённых блоков/таймкодов.

Справочник API

Ниже — назначение всех production routes. Точные request/response schemas и возможность выполнить запрос находятся в Swagger UI; контракт для генераторов клиентов — в OpenAPI JSON. Предпочтительный base path: /neuro-subs-api.

Состояние и релизы

Авторизация и аккаунты

Проекты, типы и project assets

Дедлайн назначения необязателен. Обычный пользователь резервирует свободную работу только себе; администратор может одним действием зарезервировать несколько непересекающихся кусков разным исполнителям. Проверка и суточное взятие исправлений сохраняют версии отдельно, а уведомления о свободном остатке существуют только внутри приложения и исчезают, когда остаток занят.

Уведомления

Перевод и метрики

Синхронизация файлов

Видео, логи и YouTube jobs

YouTube и серверные видео

Периодический sync использует distributed lock, чтобы несколько desktop-клиентов не создавали дубли. Новые entries классифицируются по rules. Неопределённые попадают в pending queue и требуют выбора типа.

• Локальная загрузка сначала использует bundled yt-dlp; сервер — fallback.
• Сервер выбирает MP4 H.264 + M4A AAC, совместимые с Windows и CapCut; AV1 намеренно не является приоритетом.
• ffprobe сохраняет width, height, resolution, codec и duration. «Неизвестно» означает отсутствие ffprobe или невозможность прочитать stream, а не неизвестное качество YouTube.
• Превью называется thumbnail_<project_id>.png, чтобы старый файл с похожим заголовком не приклеился к новому ролику.
• Media download поддерживает HTTP Range и выдаётся по HMAC-ссылке с expiry.

Перевод и субтитры

1. Получить ручной SRT. Auto captions используются только по явному выбору.
2. Извлечь непустые блоки в original_text.
3. Перевести line-preserving job: число строк на выходе обязано совпасть.
4. Записать translated_text, running summary и usage.
5. Создать translated_with_eng для ручной проверки.
6. Нарезать new_timestamps и собрать final SRT.
7. Импортировать в CapCut, расставить дорожки, проверить оформление.

Сервер принимает не более 5 000 строк и 2 000 000 символов за запрос. Пустая модельная строка для непустого источника, расхождение числа строк и нулевое число OpenAI requests считаются ошибкой. API key хранится только на сервере.

Разрешённые модели: gpt-5.4-mini, gpt-5.6-luna, gpt-5.6-terra, gpt-5.6-sol. Фактический список всегда проверяется через GET /translate/models.

CapCut drafts и оформление

Сервер хранит переносимую копию draft, а не абсолютные локальные пути. Перед загрузкой Python bridge нормализует структуру и прикладывает необходимые assets. Метаданные revision позволяют выбрать направление копирования без случайной перезаписи.

• Локальное имя CapCut draft персонально для аккаунта.
• Первичное создание локальной основы не загружает её автоматически; upload — отдельное явное действие.
• Фиолетовая кнопка загружает текущий draft на сервер после подготовки.
• Статус синхронизации использует визуальный хэш субтитров: текст, тайминги, положение, видимость, оформление и анимации учитываются, а видео, аудиоанализ, версия CapCut и служебные метаданные открытия игнорируются.
• Статус отдельно различает проекты только на сервере и реальные расхождения между существующими локальной и серверной копиями.
• Style example — короткий переносимый фрагмент оформления, отдельный от полного draft.
• При совпадении первой текстовой дорожки с new_timestamps удаляется только эта служебная дорожка; остальные не затрагиваются.
• Изменение скобок обновляет root, backup, template и актуальные timeline copies согласованно.

Сервер, Docker и релизы

Production services

Проверка после deploy

# На сервере
curl -fsS http://127.0.0.1:4183/neuro-subs-api/health/ready
docker compose -f docker-compose.server.yml ps
systemctl is-active caddy

# Снаружи
curl -fsS https://api.xn--90a5ag.space/neuro-subs-api/health/ready

Релиз Windows строится, публикует versioned ZIP, latest manifest и bootstrap archive. Клиент сверяет SHA-256 перед атомарной заменой. Версия 2.9.4 допускает удаление CapCut-драфта с копией общей метки только после проверки её байтов; чужие локальные вложения по-прежнему защищены.

Диагностика и восстановление

Новые технические ручки

• GET /health/live — liveness процесса без внешних зависимостей. Если не отвечает, проблема в контейнере, процессе или HTTP-маршруте.
• GET /health/ready — безопасная публичная readiness: версия, uptime, MongoDB latency и доступность storage. Секреты и connection strings не возвращаются.
• GET /admin/system/status — расширенный admin status: readiness, флаги конфигурации, каталоги и приблизительные counts ключевых коллекций. Значения токенов/ключей не возвращаются.

Порядок при аварии

1. Проверить публичный readiness URL.
2. Если он недоступен — SSH/Tailscale/LAN и локальный readiness origin.
3. Если origin ready — проверить Caddy, проброс портов 80/443 и DNS сервера.
4. Если origin degraded — смотреть конкретный failed check; не перезапускать всё вслепую.
5. После восстановления проверить login, project list, manifest diff и media health.
6. Только затем запускать sync или deploy.

Безопасность и целостность

• Пароли: PBKDF2-SHA256 с индивидуальной случайной солью и 210 000 итераций.
• Session tokens хранятся в виде SHA-256 hash; исходный token показывается только при создании.
• Admin actions проверяют роль на сервере, а не только скрываются в UI.
• Пути нормализуются и не могут выйти через .. за разрешённый root.
• Uploads ограничены по размеру, chunk index, SHA-256 и expected revision.
• Media links подписаны HMAC, имеют expiry и не кэшируются публично.
• API не возвращает Mongo URI, OpenAI key, media signing secret или Telegram token.
• Публичная диагностика содержит только безопасные boolean/latency/size данные.

История ключевых релизов

Purpose and system boundaries

Sub Video Manager tracks subtitle projects from YouTube discovery to publication: metadata, source subtitles, translation, timing, review, formatting, CapCut drafts, server files and final publication links.

The desktop client is the primary workspace. The API is the canonical shared-data and coordination layer. Local directories remain the user's working copy. Large video files have a separate lifecycle and storage service.

Architecture

Production API: https://api.xn--90a5ag.space/neuro-subs-api. Caddy terminates public HTTPS and proxies requests to the local API port.

Authentication and roles

POST /auth/login returns a random bearer token. Protected requests use Authorization: Bearer <token> and report the desktop version through X-Neuro-Subs-Client-Version.

CapCut bindings are account-specific. The API exposes only the requesting user's local draft name.

Theme preferences are local to the normalized login and schema version. Dark, light, system, eight presets and custom accents are not synchronized through account preferences; on-accent text is contrast-adjusted.

Project model

Legacy date input accepts ISO, dotted DMY and Russian month names. New writes use server-owned BSON UTC instants; when only a calendar date is known it remains explicitly marked date_only. Invalid input must not silently erase a valid stored value.

Content types

Types are not maintained as an independent fixed list. The canonical source is content_type_rules, where each keyword maps to a content type. Available types are derived from rules and existing projects.

1. Normalize the YouTube title.
2. Find matching keyword rules.
3. Prefer the longest keyword, then the more specific type, then the earlier rule.
4. If nothing matches, ask the user to select a type or create a new rule.
5. Store the type on the project and update the local directory mapping.

All year-specific STAYweeK variants collapse to canonical STAYweeK. Changing a type moves/remaps the local directory but does not move the server namespace, because server files are keyed by project ID.

Checkpoints and statuses

Published covers all required earlier stages and clears the mutually exclusive do-not-publish flag. Legacy numeric stage is migrated into checkpoints.

Files and directories

Local working path: <content_type>/<unicode-safe-project-slug>/. Canonical server sync path: projects/<project_id>/. Server video storage is separate from normal file synchronization.

Videos, partial downloads, temporary files, locks, caches, review frames and published output are excluded from normal sync.

Synchronization

Sync compares SHA-256, size, mtime and server revision. The current path schema is project-id-v1. The local mapping provides human-readable directories while the server stays stable across renames and type changes.

1. Scan the local manifest and map directories to project IDs.
2. Request decisions from /sync/manifest/diff.
3. Use batch ZIP for small sets and chunked upload for large files.
4. Validate paths, policy, size, hash and expected revision.
5. Create backups before destructive server changes.
6. Persist the latest server cursor and revisions locally.

Concurrent edits produce an explicit conflict. Deletes are revision-guarded tombstones; an outdated request cannot destroy a newer server copy.

API reference

The tables below group the complete production surface. Use Swagger UI for exact request and response schemas and OpenAPI JSON for client generation. Preferred base path: /neuro-subs-api.

YouTube and server video

A distributed lease ensures that multiple desktop clients do not import the same YouTube entry. Unknown types enter a pending queue. Local download uses bundled yt-dlp first, with server assistance as fallback.

• The server prefers MP4 H.264 video and M4A AAC audio for Windows/CapCut compatibility.
• ffprobe records width, height, resolution, codec and duration. “Unknown” means metadata extraction failed or ffprobe is unavailable.
• Canonical thumbnails use thumbnail_<project_id>.png to prevent title collisions.
• Media delivery supports HTTP Range and expiring HMAC-signed URLs.

Translation and subtitles

1. Download manual source SRT; automatic captions require explicit approval.
2. Extract source text blocks.
3. Run line-preserving translation with resumable summaries.
4. Persist translated text and usage data.
5. Generate bilingual review text.
6. Prepare timing and final SRT.
7. Import into CapCut, place tracks and review formatting.

The API rejects more than 5,000 lines or 2,000,000 characters, output line-count mismatches, empty translations for non-empty input and runs with zero OpenAI requests. The API key stays on the server.

CapCut drafts

The server stores portable drafts rather than absolute machine paths. The Python bridge prepares the bundle and preserves optimistic revision metadata before upload.

• Local CapCut draft names are account-specific.
• Creating a local base does not upload it automatically; upload is explicit.
• The purple action uploads the currently bound draft.
• Synchronization uses a subtitle visual hash: text, timing, placement, visibility, styling and animation count, while video, audio analysis, CapCut version and editor-session metadata do not.
• Project status distinguishes server-only drafts from real divergence between existing local and server copies.
• Style examples are short portable formatting fragments, separate from full drafts.
• Only the service subtitle track matching new timestamps is removed; other tracks stay intact.

Server and releases

A Windows release publishes a versioned archive, latest manifest and bootstrap package. The updater verifies SHA-256 before atomic replacement. Version 2.9.4 allows safe CapCut draft cleanup when its shared marker copy matches byte for byte; unrelated local assets remain protected.

Diagnostics and recovery

GET /health/live checks the API process without external dependencies. GET /health/ready is a safe public readiness probe with version, uptime, database latency, storage availability and the cached project-maintenance audit. The default observe maintenance mode is read-only; only explicit reconcile enables cleanup. Keep production in observe until re-identification journal pins and cleanup coordination are verified. GET /admin/system/status adds configuration flags, directories and approximate record counts without returning any secret values.

1. Probe the public readiness URL.
2. If it fails, connect through SSH/Tailscale/LAN and probe the loopback origin.
3. If the origin is ready, inspect Caddy, port forwarding for 80/443 and server DNS.
4. If the origin is degraded, follow the failed check rather than rebooting everything.
5. After recovery, verify login, project list, manifest diff and media health.

Security and integrity

• Passwords use PBKDF2-SHA256 with a random salt and 210,000 iterations.
• Session tokens are stored as SHA-256 hashes.
• Administrative permissions are enforced server-side.
• Path normalization prevents traversal beyond approved storage roots.
• Uploads validate size, chunk index, SHA-256 and expected revision.
• Media links use HMAC signatures, expiry and private no-store caching.
• Mongo URIs, OpenAI keys, signing secrets and Telegram tokens are never returned by diagnostics.

Key release history