From 7a875078d2c348eeff77345f9e9031575cc6966d Mon Sep 17 00:00:00 2001 From: Artsen Date: Sat, 25 Jul 2026 13:01:09 -0400 Subject: [PATCH] docs: add WVO Technical English standard --- CONTRIBUTING.md | 8 ++ PRIVACY.md | 4 +- README.md | 6 +- SECURITY.md | 2 +- SUPPORT.md | 27 ++-- docs/README.md | 1 + docs/api.md | 18 +-- docs/architecture.md | 12 +- docs/brand-system.md | 2 + docs/configuration.md | 35 ++++- docs/getting-started.md | 285 ++++++++++++++++++++++++++---------- docs/testing.md | 5 +- docs/troubleshooting.md | 42 ++++-- docs/user-guide.md | 46 +++--- docs/writing-style.md | 309 ++++++++++++++++++++++++++++++++++++++++ 15 files changed, 653 insertions(+), 149 deletions(-) create mode 100644 docs/writing-style.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 537a0f2..c5e21de 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -57,6 +57,14 @@ If you changed UI presentation, run `npm run review:ui-screens` and review the i - Add or update tests close to the behavior being changed. - Avoid changing encoding defaults, API contracts, or routing behavior inside unrelated refactors. +## Documentation Expectations + +- Use the controlled terminology in [WVO Technical English](docs/writing-style.md). +- Preserve exact UI labels, commands, routes, filenames, environment variables, API fields, codec names, and error codes. +- Check terminology when you add a new user-facing concept. +- Add a glossary entry to `docs/writing-style.md` when a new concept needs a stable preferred term. +- Do not claim formal ASD-STE100 compliance. + ## Do Not Commit - `node_modules` diff --git a/PRIVACY.md b/PRIVACY.md index 689cf81..852eb76 100644 --- a/PRIVACY.md +++ b/PRIVACY.md @@ -5,7 +5,7 @@ Web Video Optimizer is designed for local media processing. ## What Stays Local - Uploaded source videos are stored under the configured local `STORAGE_ROOT` or Docker volume. -- Optimized outputs, posters, captions, packages, temporary files, and `manifest.json` stay in managed local storage. +- Optimized outputs, posters, captions, website packages, temporary files, and `manifest.json` stay in managed local storage. - FFmpeg, FFprobe, and whisper.cpp processing runs on your machine when those tools are installed locally. - The app does not include analytics, telemetry, accounts, hosted storage, or remote video processing services. @@ -17,7 +17,7 @@ The browser talks to the local API base URL you configure with `VITE_API_BASE_UR ## Local Storage And Deletion -The Library and Results views can delete sources, jobs, and generated artifacts from managed storage. Storage cleanup removes stale temporary files. Docker users should remember that media persists in the `video_data` volume until it is deleted from the app or the volume is removed. +The Library and Results views can delete sources, jobs, and outputs from managed storage. Storage cleanup removes stale temporary files. Docker users should remember that media persists in the `video_data` volume until the user deletes it from the app or removes the volume. ## Logs And Metadata diff --git a/README.md b/README.md index 092853f..5c0ae73 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ Web Video Optimizer is a local-first browser workspace for turning source videos into website-ready media packages. It runs FFmpeg on your computer, creates compatible and modern video outputs, lets you compare visual quality, and packages video, poster, caption, transcript, embed, and structured-data assets for deployment. -It is intended for web developers, content teams, marketers, and creators who need deployable web video assets without sending source media to a hosted conversion service. In the default local configuration, the browser sends media to the local WVO API process and the API keeps sources and generated files on your machine. +It is intended for web developers, content teams, marketers, and creators who need deployable web video assets without sending source videos to a hosted conversion service. In the default local configuration, the browser sends media to the local WVO API process and the API keeps sources and generated files on your machine. @@ -374,7 +374,7 @@ See [Privacy](PRIVACY.md) and [Security](SECURITY.md). ## Current Limitations -WVO is still a developer beta for trusted local or trusted LAN use. It has no accounts or cloud sync. FFmpeg and FFprobe are required for core media work; caption generation requires optional whisper.cpp and a local model; URL import requires optional yt-dlp and contacts the source service. Processing speed depends on source media, codec, settings, and hardware. Browser playback support may differ from encoding support. Docker Compose startup is validated in GitHub Actions on Ubuntu, but local platform behavior can still vary. +WVO is still a developer beta for trusted local or trusted LAN use. It has no accounts or cloud sync. FFmpeg and FFprobe are required for core media work; caption generation requires optional whisper.cpp and a local model; URL import requires optional yt-dlp and contacts the source service. Processing speed depends on the source video, codec, settings, and hardware. Browser playback support may differ from encoding support. Docker Compose startup is validated in GitHub Actions on Ubuntu, but local platform behavior can still vary. ## Documentation Map @@ -382,7 +382,7 @@ WVO is still a developer beta for trusted local or trusted LAN use. It has no ac **Operators:** [Configuration](docs/configuration.md), [Privacy](PRIVACY.md), and [Security](SECURITY.md). -**Developers:** [Architecture](docs/architecture.md), [API Reference](docs/api.md), and [Testing](docs/testing.md). +**Developers:** [Architecture](docs/architecture.md), [API Reference](docs/api.md), [Testing](docs/testing.md), and [WVO Technical English](docs/writing-style.md). **Project governance:** [Contributing](CONTRIBUTING.md), [Code of Conduct](CODE_OF_CONDUCT.md), [Changelog](CHANGELOG.md), and [Support](SUPPORT.md). diff --git a/SECURITY.md b/SECURITY.md index 7982027..0c1cbe5 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -24,6 +24,6 @@ Include: ## Scope -Useful reports include path traversal, unsafe file serving, upload admission bypasses, command execution issues, unsafe archive contents, CORS mistakes, dependency vulnerabilities with a working impact, and denial-of-service cases that bypass configured limits. +Useful reports include path traversal, unsafe file serving, upload admission bypasses, command execution issues, unsafe ZIP contents, CORS mistakes, dependency vulnerabilities with a working impact, and denial-of-service cases that bypass configured limits. Reports about optional third-party tools such as FFmpeg, yt-dlp, or whisper.cpp may need to be reported upstream unless the issue is caused by how this app invokes them. diff --git a/SUPPORT.md b/SUPPORT.md index 2f85ba4..ceae802 100644 --- a/SUPPORT.md +++ b/SUPPORT.md @@ -4,13 +4,13 @@ Web Video Optimizer is a developer-beta local tool. The fastest path to help is ## Before Opening An Issue -Check: +Before you open an issue, check: - [Getting Started](docs/getting-started.md) - [Configuration](docs/configuration.md) - [Troubleshooting](docs/troubleshooting.md) -Also confirm: +Then confirm these commands: ```powershell node --version @@ -23,21 +23,22 @@ ffprobe -version Include: -- operating system -- Node.js version -- whether you are using Docker or local Node -- whether FFmpeg/FFprobe are on PATH -- relevant environment variables with private paths redacted -- steps to reproduce -- expected and actual behavior -- browser console errors or API terminal output -- whether the issue happens with a small test video +- Operating system. +- Node.js version. +- Whether you use Docker or local Node. +- Whether FFmpeg and FFprobe are on PATH. +- Relevant environment variables with private paths redacted. +- Steps to reproduce. +- Expected result. +- Actual result. +- Browser console errors or API terminal output. +- Whether the issue happens with a small test source video. -Do not attach private media unless you are comfortable sharing it publicly. +Do not attach a private source video unless you are comfortable sharing the source video publicly. ## Feature Requests -Describe the workflow you are trying to improve, the current workaround, and what success would look like. +Describe the workflow you want to improve, the current workaround, and the result that would make the workflow better. ## Security diff --git a/docs/README.md b/docs/README.md index 878b791..8cc8eea 100644 --- a/docs/README.md +++ b/docs/README.md @@ -20,4 +20,5 @@ Start here when you want the app to run, understand it, change it, or debug it. - [API Reference](api.md): local API endpoints and response behavior. - [Testing](testing.md): unit, coverage, browser E2E, real-media integration, and screenshot review commands. - [Brand System](brand-system.md): visual identity, palette, logo rules, interaction states, and screenshot asset guidance. +- [WVO Technical English](writing-style.md): controlled terminology and procedural-writing standard for documentation. - [Contributing](../CONTRIBUTING.md): branch hygiene, review expectations, and files that must not be committed. diff --git a/docs/api.md b/docs/api.md index a442065..ef858f5 100644 --- a/docs/api.md +++ b/docs/api.md @@ -18,7 +18,7 @@ http://localhost:4000 `/health` is intentionally lightweight liveness. `/ready` reports required startup checks such as managed storage, manifest load state, FFmpeg/FFprobe availability, core encoding capabilities, and storage pressure without exposing local paths, executable paths, filenames, raw commands, or manifest content. Required failures return `503` with `state: "not_ready"`. Warnings such as low storage return `200` with `state: "degraded"`. Optional tools such as yt-dlp and whisper.cpp are reported separately and are not required for core readiness. -## Sources +## Source Videos | Method | Path | Purpose | | -------- | -------------------------- | --------------------------------------------------------------------------- | @@ -27,7 +27,7 @@ http://localhost:4000 | `GET` | `/api/videos/:id/source` | Stream the source video inline. | | `GET` | `/api/videos/:id/download` | Download the original source video. | | `PATCH` | `/api/videos/:id` | Rename the source display filename. Body: `{ "originalName": "name.mp4" }`. | -| `DELETE` | `/api/videos/:id` | Delete a source and its associated managed files. | +| `DELETE` | `/api/videos/:id` | Delete a source video and its associated managed files. | ## Jobs @@ -56,12 +56,12 @@ Preview endpoints support valid `Range` headers, including suffix ranges used by ## Captions -| Method | Path | Purpose | -| ------ | ----------------------------- | ----------------------------------------------------------------------- | -| `POST` | `/api/videos/:id/subtitles` | Create a subtitle-generation job when whisper.cpp is configured. | -| `GET` | `/api/jobs/:id/captions` | Read generated caption text. | -| `PUT` | `/api/jobs/:id/captions` | Replace generated VTT captions. Body: `{ "vtt": "WEBVTT..." }`. | -| `POST` | `/api/jobs/:id/mux-subtitles` | Create a remux job that embeds subtitles into a completed video output. | +| Method | Path | Purpose | +| ------ | ----------------------------- | ---------------------------------------------------------------------- | +| `POST` | `/api/videos/:id/subtitles` | Create a caption-generation job when whisper.cpp is configured. | +| `GET` | `/api/jobs/:id/captions` | Read generated caption text. | +| `PUT` | `/api/jobs/:id/captions` | Replace generated VTT captions. Body: `{ "vtt": "WEBVTT..." }`. | +| `POST` | `/api/jobs/:id/mux-subtitles` | Create a remux job that embeds captions into a completed video output. | ## Packages @@ -75,7 +75,7 @@ Package metadata supports optional `title`, `description`, `language`, and `file | Method | Path | Purpose | | ------ | ---------------------- | --------------------------------------------- | -| `GET` | `/api/history` | Return the persisted source/job snapshot. | +| `GET` | `/api/history` | Return the persisted local library snapshot. | | `POST` | `/api/history/delete` | Bulk-delete selected `videoIds` and `jobIds`. | | `GET` | `/api/storage` | Return managed storage status. | | `POST` | `/api/storage/cleanup` | Remove stale temporary managed files. | diff --git a/docs/architecture.md b/docs/architecture.md index 3509bf2..118dcc3 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -1,6 +1,6 @@ # Architecture -Web Video Optimizer is a local-first web app with a React browser client, an Express API, shared runtime contracts, and FFmpeg-backed media workers. The system is designed around small service boundaries so video processing, storage cleanup, package generation, captions, and UI routing can evolve without changing the public API casually. +Web Video Optimizer is a local-first web app with a React browser client, an Express API, shared runtime contracts, and FFmpeg-backed media workers. The system is designed around small service boundaries so video processing, storage cleanup, website package generation, captions, and UI routing can evolve without changing the public API casually. ## System Context @@ -29,11 +29,11 @@ sequenceDiagram participant S as Storage participant F as FFmpeg/FFprobe - U->>W: Add source + U->>W: Add source video W->>A: POST /api/videos A->>S: Stage and admit upload A->>F: Probe metadata - A->>S: Persist source and manifest + A->>S: Persist source video and manifest A-->>W: Video record U->>W: Optimize for website W->>A: POST /api/videos/:id/pair @@ -74,7 +74,7 @@ The `video-core` package holds pure logic that is useful on either side of the b - job lifecycle and scheduling services - process registry and process runner - storage boundary, reservations, capacity checks, and housekeeping -- cleanup, package, caption, video, and job services +- cleanup, website package, caption, video, and job services Routes depend on the runtime interface rather than constructing services directly. This keeps tests fast and lets integration tests run against the compiled API without changing route code. @@ -128,11 +128,11 @@ erDiagram Managed storage lives under `STORAGE_ROOT`: - `uploads` stores admitted source videos. -- `outputs` stores completed job artifacts and packages. +- `outputs` stores completed job artifacts and website packages. - `tmp` stores temporary work files and upload staging. - `manifest.json` stores durable history. -The storage boundary resolves files by managed area, blocks traversal, and opens files through descriptors. Cleanup removes canceled jobs, deleted videos, orphan files, stale temporary files, and partial failed outputs. Capacity checks can reserve bytes before paired website jobs so one output is not admitted unless the pair can be scheduled safely. +The storage boundary resolves files by managed area, blocks traversal, and opens files through descriptors. Cleanup removes canceled jobs, deleted source videos, orphan files, stale temporary files, and partial failed outputs. Capacity checks can reserve bytes before paired website jobs so one output is not admitted unless the pair can be scheduled safely. ## Persistence And Recovery diff --git a/docs/brand-system.md b/docs/brand-system.md index bd82558..ed19452 100644 --- a/docs/brand-system.md +++ b/docs/brand-system.md @@ -370,6 +370,8 @@ Disallowed examples: - `AI-powered optimization engine` - `Revolutionary media workflow` +The brand document governs product voice and interface tone. [WVO Technical English](writing-style.md) governs procedural and technical documentation. The two standards are complementary: product and brand writing can explain design rationale, while setup, configuration, troubleshooting, API, and support documentation should use controlled terminology and direct procedures. + ## Accessibility And Review Normal text should meet at least 4.5:1 contrast and large text at least 3:1. Status must not rely on color alone. diff --git a/docs/configuration.md b/docs/configuration.md index ca20271..d43ec53 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -1,6 +1,33 @@ # Configuration -The API reads environment variables at startup. Restart the API after changing them. The web app reads `VITE_API_BASE_URL` when the Vite app starts or builds. +The API reads environment variables at startup. Restart the API after changing an API variable. The web app reads `VITE_API_BASE_URL` when the Vite app starts or builds. + +## Change A Configuration Value + +### Purpose + +Change WVO runtime configuration for a local development session. + +### Before You Start + +- Stop the API when you change API variables. +- Stop the Vite web app when you change `VITE_API_BASE_URL`. +- Record values that contain private local paths outside public issues and pull requests. + +### Procedure + +1. Set the environment variable in the terminal that will start the process. +2. Start or restart the affected process. +3. Open . +4. If the change affects API readiness, open . + +### Result + +The affected process starts with the new value. + +### Recovery + +If WVO does not use the new value, confirm that the variable was set in the same terminal that started the process. ## Core @@ -24,7 +51,9 @@ The API reads environment variables at startup. Restart the API after changing t | `TEMP_FILE_MAX_AGE_MS` | `86400000` | Age threshold for stale temporary cleanup. | | `HOUSEKEEPING_INTERVAL_MS` | `3600000` | Interval for background storage housekeeping. | -Managed areas are `uploads`, `outputs`, `tmp`, and `tmp/upload-staging`. Files outside those areas are not served through the API. +Managed areas are `uploads`, `outputs`, `tmp`, and `tmp/upload-staging`. The API does not serve files outside those areas. + +Important: Do not point `STORAGE_ROOT` at a directory that contains unrelated user files. Delete and cleanup actions operate inside managed storage. ## Media Jobs @@ -48,6 +77,8 @@ Managed areas are `uploads`, `outputs`, `tmp`, and `tmp/upload-staging`. Files o FFmpeg and FFprobe are invoked from PATH. +Result: If optional tools are not configured, WVO still supports local upload, probing, optimization, comparison, posters, packages, and downloads. YouTube import and caption generation remain unavailable until their variables are configured. + ## Docker Compose Docker Compose sets: diff --git a/docs/getting-started.md b/docs/getting-started.md index c57805e..e9dde80 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -4,125 +4,262 @@ Web Video Optimizer can run directly with Node.js or with Docker Compose. Local ## Requirements -- Node.js 20 or newer -- npm -- FFmpeg and FFprobe -- Git -- Optional: Docker Desktop -- Optional: yt-dlp for YouTube imports -- Optional: whisper.cpp for local caption generation +- Node.js 20 or later. +- npm. +- Git. +- FFmpeg and FFprobe on PATH. +- A modern browser. +- Optional: Docker Desktop. +- Optional: yt-dlp for YouTube imports. +- Optional: whisper.cpp for local caption generation. -## Local Node +## Start WVO With Local Node -Install dependencies: +### Purpose -```powershell -git clone https://github.com/Artsen/web-video-optimizer.git -cd web-video-optimizer -npm ci -``` +Start the local API and browser application for development. -Start both API and web: +### Before You Start -```powershell -npm run dev -``` +- Install Node.js 20 or later. +- Install FFmpeg and FFprobe. +- Put FFmpeg and FFprobe on PATH. + +### Procedure + +1. Clone the repository. + + ```powershell + git clone https://github.com/Artsen/web-video-optimizer.git + ``` + +2. Open the repository root. + + ```powershell + cd web-video-optimizer + ``` + +3. Install dependencies. -Open . The API runs at and must remain running while the web interface is used. + ```powershell + npm ci + ``` -If PowerShell blocks `npm.ps1`, use: +4. Start the API and web app. + + ```powershell + npm run dev + ``` + +5. Open . + +### Result + +The browser opens WVO. The API listens on . Keep the API running while you use the web interface. + +### Recovery + +If PowerShell blocks `npm.ps1`, run: ```powershell npm.cmd run dev ``` -## Separate Dev Consoles +If the browser cannot reach the API, confirm that port `4000` is available and that the API process is running. -You can also run the API and web app separately. This is useful when you want each service in its own terminal: +## Start Services In Separate Consoles -Console 1: +### Purpose -```powershell -npm run dev:api -``` +Run the API and web app in separate terminals. -Console 2: +### Procedure -```powershell -npm run dev:web -``` +1. Start the API. -The default API is . The default web app is . + ```powershell + npm run dev:api + ``` -## Docker Compose +2. In a second terminal, start the web app. -Docker is optional for ordinary local development. The project validates Docker Compose startup in GitHub Actions on Ubuntu. + ```powershell + npm run dev:web + ``` -```powershell -git clone https://github.com/Artsen/web-video-optimizer.git -cd web-video-optimizer -docker compose up --build -``` +3. Open . -Open . +### Result -The API listens on . Runtime media is stored in the Docker `video_data` volume. Inside Docker, the API binds to `0.0.0.0` with `ALLOW_LAN_ACCESS=true` so the published host port can reach the container; ordinary local Node development still defaults to loopback-only API binding. +The API listens on . The web app runs at . -Stop the app with `Ctrl+C`, then run: +## Start WVO With Docker Compose -```powershell -docker compose down -``` +### Purpose + +Start WVO with Docker Compose when Docker is available. + +### Before You Start + +- Install Docker Desktop. +- Decide whether the Docker `video_data` volume can store local runtime media. + +### Procedure + +1. Clone the repository. + + ```powershell + git clone https://github.com/Artsen/web-video-optimizer.git + ``` + +2. Open the repository root. + + ```powershell + cd web-video-optimizer + ``` + +3. Start Docker Compose. + + ```powershell + docker compose up --build + ``` + +4. Open . + +### Result + +The API listens on . Docker stores runtime media in the `video_data` volume. Inside Docker, the API binds to `0.0.0.0` with `ALLOW_LAN_ACCESS=true` so the published host port can reach the container. + +### Stop Docker Compose + +1. Press `Ctrl+C`. +2. Stop the containers. + + ```powershell + docker compose down + ``` Use `docker compose down -v` only when you intentionally want to remove the stored media volume. -## FFmpeg +## Check FFmpeg -The API expects `ffmpeg` and `ffprobe` on PATH. +### Purpose -```powershell -ffmpeg -version -ffprobe -version -``` +Confirm that the API can invoke FFmpeg and FFprobe. -If either command fails, install FFmpeg and reopen the terminal so PATH changes apply. +### Procedure -## Optional LAN Access +1. Check FFmpeg. -The API defaults to loopback-only binding. To access it from another device on your trusted network, configure both the API bind address and CORS origins: + ```powershell + ffmpeg -version + ``` -```powershell -$env:HOST = "0.0.0.0" -$env:ALLOW_LAN_ACCESS = "true" -$env:CORS_ORIGIN = "http://localhost:5173,http://YOUR-LAN-IP:5173" -$env:VITE_API_BASE_URL = "http://YOUR-LAN-IP:4000" -``` +2. Check FFprobe. -The API has no login system. Only enable LAN access on a trusted network. + ```powershell + ffprobe -version + ``` -## Optional YouTube Import +### Recovery -Install yt-dlp and set: +If either command fails, install FFmpeg, add the FFmpeg `bin` directory to PATH, and reopen the terminal. -```powershell -$env:YT_DLP_BIN = "C:\path\to\yt-dlp.exe" -``` +## Enable Optional LAN Access + +### Purpose + +Allow another device on a trusted local network to use WVO. + +### Warning + +The API has no login system. Enable LAN access only on a trusted network. + +### Procedure + +1. Set the API bind host. + + ```powershell + $env:HOST = "0.0.0.0" + ``` + +2. Allow non-loopback binding. + + ```powershell + $env:ALLOW_LAN_ACCESS = "true" + ``` + +3. Set allowed web origins. + + ```powershell + $env:CORS_ORIGIN = "http://localhost:5173,http://YOUR-LAN-IP:5173" + ``` + +4. Set the browser API base URL. + + ```powershell + $env:VITE_API_BASE_URL = "http://YOUR-LAN-IP:4000" + ``` + +5. Restart both dev servers. -The API automatically passes its Node runtime to yt-dlp as the JavaScript runtime. Override it only if needed: +### Result + +Another device on the trusted network can open the web app and send requests to the local API. + +## Enable Optional YouTube Import + +### Purpose + +Allow WVO to import supported YouTube URLs through yt-dlp. + +### Procedure + +1. Install yt-dlp. +2. Set the yt-dlp executable path. + + ```powershell + $env:YT_DLP_BIN = "C:\path\to\yt-dlp.exe" + ``` + +3. Restart the API. + +### Result + +WVO can import supported YouTube URLs. The yt-dlp tool contacts YouTube and related network endpoints when it downloads the provided URL. + +### Optional Override + +The API passes its Node runtime to yt-dlp as the JavaScript runtime. Override the runtime only if needed: ```powershell $env:YT_DLP_JS_RUNTIME = "node:C:\Program Files\nodejs\node.exe" ``` -Only supported YouTube URLs are accepted. +## Enable Optional Local Captions -## Optional Local Captions +### Purpose -Install whisper.cpp and download a local model. Then set: +Allow WVO to generate captions with local whisper.cpp. -```powershell -$env:WHISPER_CPP_BIN = "C:\path\to\whisper-cli.exe" -$env:WHISPER_CPP_MODEL = "C:\path\to\ggml-base.en.bin" -``` +### Procedure + +1. Install whisper.cpp. +2. Download a local whisper.cpp model. +3. Set the whisper.cpp executable path. + + ```powershell + $env:WHISPER_CPP_BIN = "C:\path\to\whisper-cli.exe" + ``` + +4. Set the model path. + + ```powershell + $env:WHISPER_CPP_MODEL = "C:\path\to\ggml-base.en.bin" + ``` + +5. Restart the API. + +### Result -Restart the API after changing these variables. Caption generation runs locally with the configured executable and model. +Caption generation runs locally with the configured executable and model. diff --git a/docs/testing.md b/docs/testing.md index e79bcd3..942e3ce 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -50,7 +50,7 @@ Unit tests cover: - shared contract schemas - video-core helpers for filenames, encoding settings, FFmpeg arguments, metadata, and progress parsing -- API config parsing, request validation, route behavior, repositories, services, storage boundaries, capacity policy, reservations, persistence, scheduler behavior, process handling, cleanup, packages, captions, and downloads +- API config parsing, request validation, route behavior, repositories, services, storage boundaries, capacity policy, reservations, persistence, scheduler behavior, process handling, cleanup, website packages, captions, and downloads - frontend route state, API client behavior, job event wiring, feature derivations, component behavior, compare state, poster dialog accessibility, and upload workflows Unit tests use Vitest and should not require real media tools. @@ -80,7 +80,8 @@ The compiled API media integration suite requires FFmpeg and FFprobe on PATH. It - poster generation - package creation - privacy of DTOs -- cleanup and deletion +- cleanup of temporary or partial files +- deletion of selected durable data - timeout cleanup and later work acceptance - graceful shutdown and recovery states - scheduler FIFO behavior and cancelation paths diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 64fe1d4..1a883b7 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -2,7 +2,9 @@ ## `node`, `npm`, Or `git` Is Not Recognized -Reopen PowerShell after installing tools so PATH changes apply. You can also temporarily add common install paths: +Cause: The terminal usually does not have the tool directory on PATH. + +Recovery: Reopen PowerShell after installing tools so PATH changes apply. You can also temporarily add common install paths: ```powershell $env:Path = "C:\Program Files\nodejs;C:\Program Files\Git\cmd;C:\Program Files\GitHub CLI;$env:Path" @@ -10,28 +12,30 @@ $env:Path = "C:\Program Files\nodejs;C:\Program Files\Git\cmd;C:\Program Files\G ## PowerShell Blocks `npm.ps1` -Use `npm.cmd`: +Recovery: Use `npm.cmd`: ```powershell npm.cmd run dev ``` -Or update your PowerShell execution policy for your user account if you are comfortable doing that. +You can also update the PowerShell execution policy for your user account if you are comfortable with that system change. ## FFmpeg Or FFprobe Is Missing -Confirm both commands work: +Recovery: Confirm both commands work: ```powershell ffmpeg -version ffprobe -version ``` -Install FFmpeg, add its `bin` directory to PATH, and restart the terminal. +If either command fails, install FFmpeg, add the FFmpeg `bin` directory to PATH, and restart the terminal. ## Ports Are In Use -The defaults are API `4000` and web `5173`. Stop stale dev processes or choose another port: +Cause: Another process is using API port `4000` or web port `5173`. + +Recovery: Stop stale dev processes or choose another API port: ```powershell $env:PORT = "4001" @@ -40,7 +44,9 @@ $env:VITE_API_BASE_URL = "http://localhost:4001" ## Browser Cannot Upload From Another Laptop -When using a LAN IP, configure both the API and web origin: +Cause: The browser on the other device cannot reach the local API, or CORS does not allow the LAN origin. + +Recovery: When using a LAN IP, configure both the API bind address and the web origin: ```powershell $env:HOST = "0.0.0.0" @@ -49,15 +55,19 @@ $env:CORS_ORIGIN = "http://localhost:5173,http://YOUR-LAN-IP:5173" $env:VITE_API_BASE_URL = "http://YOUR-LAN-IP:4000" ``` -Restart both dev servers. Only use this on a trusted network because the API has no login. +Restart both dev servers. Only use LAN access on a trusted network because the API has no login. ## Video Preview Is Blank But Download Works -Some codec/container combinations cannot be decoded by every browser. Use the compatible H.264 MP4 fallback for broad preview support. WebM and AV1 require browser support. The API supports byte ranges for browser playback, including suffix ranges. +Cause: Some codec and container combinations cannot be decoded by every browser. + +Recovery: Use the MP4 fallback for broad preview support. WebM and AV1 require browser support. The API supports byte ranges for browser playback, including suffix ranges. ## Upload Fails With `413` -The file or JSON body is above the configured limit. Check: +Cause: The source video or JSON body is above the configured limit. + +Recovery: Check: - `UPLOAD_FILE_SIZE_LIMIT_BYTES` - `JSON_BODY_LIMIT_BYTES` @@ -66,7 +76,9 @@ Restart the API after changing limits. ## Job Fails With Storage Or Capacity Errors -Check the Library storage status and cleanup stale temporary files. You can also adjust: +Cause: Managed storage does not have enough allowed space for the requested job. + +Recovery: Check the Library storage status and clean up stale temporary files. You can also adjust: - `MIN_FREE_STORAGE_BYTES` - `MAX_MANAGED_STORAGE_BYTES` @@ -76,7 +88,7 @@ Do not point `STORAGE_ROOT` at a folder containing unrelated user files. ## YouTube Import Does Nothing Or Fails -Confirm yt-dlp works in the terminal and set `YT_DLP_BIN`. Some YouTube extraction paths require a JavaScript runtime; the API passes its current Node runtime by default, but you can override `YT_DLP_JS_RUNTIME`. +Recovery: Confirm yt-dlp works in the terminal and set `YT_DLP_BIN`. Some YouTube extraction paths require a JavaScript runtime; the API passes its current Node runtime by default, but you can override `YT_DLP_JS_RUNTIME`. Only HTTPS YouTube hosts are accepted. @@ -87,11 +99,13 @@ Caption generation requires both: - `WHISPER_CPP_BIN` - `WHISPER_CPP_MODEL` -Restart the API after setting them. If the video already has embedded subtitles, the app reports that status from FFprobe. +Recovery: Restart the API after setting them. If the source video already has an embedded subtitle track, WVO reports that status from FFprobe. ## `npm ci` Fails On Windows With Locked Files -Stop stale dev/test Node processes that are using project dependencies, then rerun the command. Do not delete source files to work around a local lock. +Cause: A stale dev or test process can keep a dependency file locked. + +Recovery: Stop stale dev/test Node processes that are using project dependencies, then rerun the command. Do not delete source files to work around a local lock. ## Where Test Artifacts Go diff --git a/docs/user-guide.md b/docs/user-guide.md index 50545d2..0b44386 100644 --- a/docs/user-guide.md +++ b/docs/user-guide.md @@ -1,21 +1,21 @@ # User Guide -Web Video Optimizer is built around a source workspace. Prepare is where you add or tune a source; Results is where completed outputs, packages, captions, and comparison tools become useful. +Web Video Optimizer is built around a source workspace. Prepare is where you add or review a source video. Results is where completed outputs, website packages, captions, and comparison tools become useful. ## Add A Source -Use the Prepare screen to upload a video by choosing a file or dragging one into the upload area. If yt-dlp is configured, you can also paste a supported YouTube URL and let the API import it first. +Use the Prepare view to upload a source video by choosing a file or dragging one into the upload area. If yt-dlp is configured, paste a supported YouTube URL and let the API import the source video. ![Prepare workspace](assets/screenshots/prepare-dark.webp) -After a source is admitted, the app shows metadata such as dimensions, duration, codecs, audio status, subtitle tracks, and estimated source size. The source can be renamed without changing the underlying media content. +Result: After WVO admits the source video, WVO shows dimensions, duration, codecs, audio status, embedded subtitle tracks, and estimated source size. The user can rename the source without changing the underlying media content. ## Optimize For Website -The main website workflow creates two outputs: +The Optimize for website workflow creates two outputs: -- a compatible H.264 MP4 fallback -- a modern WebM/AV1 output +- Create an MP4 fallback. +- Create a modern WebM output. Jobs are queued through the API scheduler. Progress appears in the Results workspace and survives browser refreshes through the saved history manifest. @@ -25,14 +25,14 @@ Jobs are queued through the API scheduler. Progress appears in the Results works In Results you can: -- select an output -- preview video or poster output -- download the original source or completed jobs -- rename completed job filenames -- cancel queued or running work -- delete outputs or sources -- create posters, captions, remuxed subtitles, and packages -- copy generated embed code +- Select an output. +- Preview a video output or poster output. +- Download the source video or completed outputs. +- Rename completed output filenames. +- Cancel queued or running jobs. +- Delete outputs or sources. +- Create posters, captions, remuxed subtitle outputs, and website packages. +- Copy generated embed code. Processed historical sources open directly to Results. New or unprocessed sources open to Prepare. @@ -40,7 +40,7 @@ Processed historical sources open directly to Results. New or unprocessed source ![Compare theatre](assets/screenshots/compare-wipe-dark.webp) -Compare is a theatre-style view for checking visual quality. It supports grid layouts, wipe comparison, and A/B comparison. Playback can be synchronized across videos. +Compare is a theatre-style view for checking visual quality. It supports Grid layouts, Wipe comparison, and A/B comparison. Playback can be synchronized across videos. The URL restores selected output, mode, layout, and visible versions. Playback time, volume, zoom, pan, wipe position, and fullscreen are intentionally treated as temporary review state. @@ -54,15 +54,15 @@ If FFprobe finds embedded subtitle tracks, the app reports them. If no subtitle Generated captions can be: -- previewed over the video -- edited in the caption theatre -- downloaded as `.vtt` or `.srt` -- included as sidecar files in the ZIP package -- remuxed into completed MP4/WebM outputs +- Previewed over the video. +- Edited in the caption theatre. +- Downloaded as `.vtt` or `.srt`. +- Included as caption files in the website package. +- Remuxed into completed MP4 or WebM outputs. ## Website Package -The package job creates a ZIP intended for website handoff. It can include optimized videos, poster artwork, caption files, transcript markup, and SEO-friendly `VideoObject` structured data. +The package job creates a website package for website handoff. The website package can include optimized videos, poster artwork, caption files, transcript markup, and SEO-friendly `VideoObject` structured data. The embed snippet uses local relative filenames so the video, poster, and captions can be served from the same site directory. @@ -70,10 +70,10 @@ The embed snippet uses local relative filenames so the video, poster, and captio ![Custom export controls](assets/screenshots/custom-export-dark.webp) -Custom Export lets you choose container, codec, width, frame rate, CRF, preset, audio mode, bitrate, sample rate, channel count, fast-start, metadata stripping, and output filename. Use it when the default website pair is not the right fit. +Custom Export lets the user choose container, codec, width, frame rate, CRF, preset, audio mode, bitrate, sample rate, channel count, fast-start, metadata stripping, and output filename. Use Custom Export when the default website pair is not the right fit. ## Library And Storage -The Library view shows previous sources and jobs from the manifest. You can reopen sources, delete old videos or outputs, and run storage cleanup for stale temporary files. +The Library view shows previous sources and jobs from the manifest. The user can reopen sources, delete old sources or outputs, and run storage cleanup for stale temporary files. The API stores managed media under `STORAGE_ROOT`; Docker uses the `video_data` volume. diff --git a/docs/writing-style.md b/docs/writing-style.md new file mode 100644 index 0000000..2bddeea --- /dev/null +++ b/docs/writing-style.md @@ -0,0 +1,309 @@ +# WVO Technical English + +WVO Technical English is the project-specific house style for clear technical documentation in Web Video Optimizer. It is informed by ASD-STE100 Simplified Technical English principles, but WVO does not claim formal ASD-STE100 compliance. + +This document does not reproduce or copy the ASD-STE100 controlled dictionary. It defines WVO-specific terminology and writing rules for this repository. + +## Purpose + +WVO Technical English keeps instructions clear, consistent, and safe for: + +- User procedures. +- Setup instructions. +- Configuration documentation. +- Troubleshooting. +- Error explanations. +- API documentation. +- Generated package instructions. +- Future localization. + +The standard reduces terminology drift, vague instructions, unnecessary synonyms, ambiguous pronouns, long sentences, and promotional language. + +## Source Of Truth + +The checked-in application and API contracts remain the source of truth for behavior. Documentation must not describe planned, inferred, or partially implemented functionality as available. + +Technical names, commands, filenames, paths, API fields, codec names, and code must remain exact. Product-specific nouns and verbs are allowed when they are defined and used consistently. + +## Application Levels + +### Level 1: Controlled Procedural Documentation + +Apply the strongest rules to: + +- `docs/getting-started.md` +- `docs/user-guide.md` +- `docs/configuration.md` +- `docs/troubleshooting.md` +- `SUPPORT.md` +- Generated package instructions, when the source template is documentation +- Installation, recovery, cleanup, and destructive-action procedures + +Level 1 documents should use direct procedures, clear results, and recovery actions. + +### Level 2: Controlled Technical Reference + +Apply terminology and clarity rules, but preserve formal syntax and necessary density in: + +- `docs/api.md` +- `docs/testing.md` +- `docs/architecture.md` +- `CONTRIBUTING.md` +- `SECURITY.md` +- `PRIVACY.md` + +Level 2 documents can use precise technical terms when the term is necessary. + +### Level 3: Product And Brand Explanation + +Use normal clear product language rather than strict controlled prose in: + +- `README.md` +- `docs/brand-system.md` +- `CHANGELOG.md` +- Pull request descriptions +- Product positioning and design rationale + +Level 3 content must still avoid vague, inflated, or misleading claims. + +## Core Rules + +1. Use one preferred term for one concept. +2. Do not change terminology only to avoid repetition. +3. Use active voice for procedures. +4. Start each procedural step with an action when possible. +5. Put one primary action in each numbered step. +6. Put conditions before the action. +7. Use short, direct sentences. Treat approximately 20 words as a review signal, not an absolute limit. +8. Avoid ambiguous pronouns when the referenced object is not immediately clear. +9. State the actor: the user selects, WVO creates, the API returns, FFmpeg encodes, or the browser downloads. +10. Distinguish requirements from recommendations. +11. Give a recovery action for each recoverable error. +12. Explain consequences before destructive actions. +13. Preserve exact technical strings. +14. Define abbreviations when the audience might not know them. +15. Use real product and codec names. +16. Avoid promotional language in technical documentation. +17. Do not hide technical limitations. +18. Keep notes, warnings, and results distinct. +19. Use parallel grammar in lists. +20. Use direct button and menu names. + +## Requirements, Recommendations, And Capabilities + +Use these words consistently: + +- `must` for requirements. +- `should` for recommendations. +- `can` for capability. +- `may` for permission or possibility only when the meaning is clear. + +Do not use `should` when an instruction is mandatory. + +## Exact Technical Strings + +Do not rewrite: + +- Commands. +- Environment variable names. +- API routes. +- JSON fields. +- Filenames. +- Paths. +- Codec identifiers. +- Package names. +- Error codes. +- HTTP status codes. + +Use real names such as FFmpeg, FFprobe, yt-dlp, whisper.cpp, H.264, AV1, VP9, AAC, Opus, libx264, libaom-av1, libvpx-vp9, and libopus. + +Common labels such as API, URL, HTTP, JSON, ZIP, MP4, WebM, AV1, H.264, AAC, and Opus do not need repeated definitions after the first useful definition in a document. + +## Preferred Terminology + +| Preferred term | Meaning | Avoid as interchangeable synonyms | +| ----------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | +| source video | The video that the user uploads or imports. | input asset, incoming clip, original media | +| source | An acceptable short form after source video is established in the same context. | media object, item, asset when referring specifically to the source video | +| original file | The file before WVO admits, copies, or changes it. | source when the distinction matters | +| output | A file created by a completed WVO job. | result file, converted media, generated version | +| artifact | A build, test, or implementation file created by a tool. Acceptable in architecture, tests, and build systems. | output in user procedures | +| job | A queued, running, completed, canceled, or failed unit of processing. | task, process, operation, conversion run | +| website package | The ZIP handoff package that contains selected website assets and instructions. | bundle, archive, delivery package, handoff ZIP | +| local library | The source and job history that WVO stores on the current computer. | database, media archive, history store | +| MP4 fallback | The compatible H.264 and AAC output. | legacy file, compatibility copy, old format | +| modern WebM output | The modern WebM output, normally encoded with AV1 and Opus. | advanced version, next-generation file | +| poster | The still image displayed before video playback. | thumbnail, cover, preview image when referring to the generated poster | +| captions | Timed text stored as VTT or SRT. | subtitles when the distinction matters | +| embedded subtitle track | A subtitle stream already present in the source video. | captions | +| caption file | A VTT or SRT sidecar file created or exported by WVO. | subtitle file when the distinction matters | +| transcript | Non-timed readable text derived from captions. | captions | +| Optimize for website | The primary recommended workflow that creates the standard website outputs. Preserve this label. | default conversion, quick export | +| Custom Export | The workflow for manually selected output settings. Preserve this label. | advanced export, manual mode | +| Compare | The application view for visual comparison. Preserve implemented mode names exactly. | comparison screen when referring to the view label | +| managed storage | Storage controlled and inventoried by WVO. | app folder, media archive | +| storage root | The configured root directory for WVO-managed files. | data folder when the exact setting matters | +| temporary file | An intermediate file that WVO can remove through safe cleanup. | durable output | +| local | Processing or storage that occurs on the user's computer. | private, secure, offline, anonymous | +| readiness | API startup and dependency state. | health when referring to detailed startup checks | +| health | Lightweight liveness state. | readiness when referring to `/ready` | +| cleanup | Removal of eligible temporary files or orphaned managed data. | deletion of user-selected durable data | +| delete | Removal of a user-selected durable source, output, or job. | cleanup | +| download | Transfer a file from the local API to the browser or selected destination. | export | +| export | Create a new encoded output through Custom Export or an optimization workflow. | download | + +## Domain Distinctions + +### Source Video Versus Original File + +Use `source video` for the admitted video in WVO. Use `original file` for the file before WVO changes or copies it. Do not alternate between the terms without considering the distinction. + +### Output Versus Artifact + +Use `output` in user documentation. Use `artifact` in architecture, tests, build systems, and internal implementation documentation when the term describes tool-created files. + +### Captions Versus Subtitles + +Use `captions` for generated VTT or SRT timed text. Use `embedded subtitle track` for a subtitle stream that is already present in the source video. Do not remove a technically meaningful distinction only for vocabulary consistency. + +### Download Versus Export + +Use `download` when the browser receives a completed file from the local API. Use `export` when WVO creates a new encoded output. Do not use these terms interchangeably. + +### Delete Versus Cleanup + +Use `delete` when the user removes a selected durable source, output, or job. Use `cleanup` when WVO removes eligible temporary files or orphaned managed data. Never describe durable deletion as cleanup. + +### Ready Versus Completed + +Use `completed` for a job status. Use `ready` for application readiness or publish readiness only when the feature exists. Do not use `ready` as a replacement for `completed`. + +## Procedure Format + +Use this structure when a document gives a sequence of actions: + +### Purpose + +State what the procedure does. + +### Before You Start + +List requirements, dependencies, permissions, and possible data effects. + +### Procedure + +Use numbered actions. Put one primary action in each step. + +### Result + +State the expected observable result. + +### Recovery + +State what to check when the result does not occur. + +Example: + +```text +Purpose + +Start WVO for local development. + +Before you start + +- Install Node.js 20 or later. +- Install FFmpeg and FFprobe. +- Put FFmpeg and FFprobe on PATH. + +Procedure + +1. Open a terminal in the repository root. +2. Run npm ci. +3. Run npm run dev. +4. Open http://localhost:5173. + +Result + +The browser opens the WVO application. The API listens on http://localhost:4000. + +Recovery + +If the application cannot reach the API, confirm that port 4000 is available and that the API process is running. +``` + +## Error Format + +Use this structure for recoverable errors: + +```text +Problem. + +Cause, when known and useful. + +Recovery action. +``` + +Examples: + +- FFmpeg was not found. Install FFmpeg or configure its path. +- WVO cannot create the output because managed storage is full. Delete unused outputs or change the storage root. + +Avoid generic messages such as: + +- FFmpeg error. +- Something went wrong. +- Unexpected failure. + +Do not expose: + +- Stack traces. +- Absolute private paths. +- Environment values. +- User filenames when they are not needed. +- Imported URLs. +- Caption contents. +- Manifest contents. + +## Labels For Notes And Warnings + +Use labels consistently: + +- **Note:** Helpful information that is not required. +- **Important:** Required information that prevents failure or data loss. +- **Warning:** A condition that can cause data loss, unsafe exposure, or significant disruption. +- **Result:** The expected state after a procedure. +- **Example:** A sample command, response, or configuration. + +Do not use `Warning` for general advice. + +## Promotional Language + +Do not use promotional claims in technical documentation. Avoid: + +- Revolutionary. +- Magical. +- Perfect. +- Effortless. +- Intelligent. +- Next-generation. +- Unleash. +- Transform your workflow. +- Best-in-class. +- AI-powered, unless a feature actually uses AI and the detail is relevant. + +Prefer specific behavior and limits. + +## Review Checklist + +Before committing documentation, check that: + +- The actor is clear. +- The action is clear. +- The result is clear. +- The recovery action is present when the result can fail. +- UI labels match the application. +- Commands, routes, filenames, fields, and codec names are exact. +- Preferred terminology is used consistently. +- Technical limitations are visible. +- No formal ASD-STE100 compliance is claimed. +- No ASD-STE100 dictionary content is copied.