# How it works

> Projects, where the media comes from, the processing service and where the results go.

Three ideas cover the whole API: a **project** says what to do, its **input folder** is where
media goes in, and its **output folder** is where results come out. A project can also read its
media from an **RSS or Media RSS feed** and publish a dubbed copy of that feed.

```mermaid
flowchart LR
  subgraph You
    U[Your media]
  end
  subgraph Project["Project · config"]
    I[(input/)] --> S[Processing service<br/>transcribe → translate → dub → package]
    S --> O[(output/)]
  end
  U -- "upload<br/>(AWS CLI or API)" --> I
  F[Your RSS or Media RSS feed] -. "or: each item's media,<br/>downloaded" .-> I
  O -- "download<br/>(presigned URL or AWS CLI)" --> R[Your results]
  O -. "and: a feed per language,<br/>public URL" .-> P[Players, partners]
```

## Projects

A project is one set of instructions, the `config`:

- **sourceMedia:** where the media comes from: the project's input folder, or a feed;
- **transcription:** the language spoken in the media, and the speech-recognition engine;
- **translations:** zero or more target languages, each with a translation engine and optionally
  a voice to dub it with (`ttsOptions`);
- **outputs:** where the results go (the output folder, and for a feed project a feed per
  language), each with the files to produce for every input: videos with chosen audio and
  subtitle tracks, audio files, subtitle files.

Every file in the project's input folder is processed with that config. A season of a show is
typically one project; a different language set or a different output format is another project.
See [Projects](/vod-express/concepts/projects) and [Configure a project](/vod-express/configuration/overview).

## The folders

Each project has its own place in SyncWords' S3 storage, given in its `storage` field:

```json
"storage": {
  "path": "s3://sw-vod-express/projects/141/01m3k8jnrdw509457nhz7w81bq/",
  "inputPath": "s3://sw-vod-express/projects/141/01m3k8jnrdw509457nhz7w81bq/input/",
  "outputPath": "s3://sw-vod-express/projects/141/01m3k8jnrdw509457nhz7w81bq/output/"
}
```

- **`input/`** holds your source media. Upload with the API (no AWS account needed) or with the
  AWS CLI and a role vended for your account. Subfolders are allowed. A project that reads a
  [feed](/vod-express/concepts/inputs#feeds) downloads each item's media here itself, and
  takes no uploads.
- **`output/`** receives the results, named from each input by the item's `nameTemplate`
  (`episode 01.mp4` → `episode 01.es.mp4`), in the same subfolders as the input. A feed
  project's re-published feeds are written under `output/feeds/`.

The API never handles your files' bytes: uploads and downloads go straight between you and S3.

## The processing service

A running project has a processing service watching its input folder. It picks up each new file,
works through it, writes the outputs and moves on. Several files are processed in parallel.

For each file it:

1. **transcribes** the speech, with speaker diarization;
2. **translates** each utterance into every target language;
3. **dubs** each translation that has `ttsOptions`: synthesises the lines with the chosen voices,
   timed to the original speech, and mixes them over the original background;
4. **packages** the outputs: muxes audio and subtitle tracks into videos, writes audio and subtitle
   files.

The service stops itself 30 minutes after its last file finished, so an idle project costs
nothing, and starts again on its own when more files land in the input folder (unless you turn
`startOnNewFiles` off). A project
that reads a feed is never stopped for being idle: it keeps reading the feed, every 30 seconds,
for new items. See [the processing service](/vod-express/concepts/projects#the-processing-service).

## Following progress

`GET /projects/{id}/files` lists every input with its state (`pending`, `processing`, `done`,
`failed`) and the outputs it will produce, each marked `available` once written. To be told
instead of asking, register a [webhook](/vod-express/guides/webhooks): it is called when a file is done or
failed and when a project stops. Or poll the listing, as described in
[Monitoring](/vod-express/guides/monitoring).

## Billing

Usage is recorded per input file when it is done, by the file's duration: once for its captions
in the transcription language, once for each translated language, and separately once for each
dubbed language. Output formats are not billed separately, so three video formats of one Spanish
dub count as one Spanish dub, and a file that is only transcribed is billed for its captions
alone. A file that fails is not billed. Retrying a file does not bill it again; uploading
different content under the same name does.

Billing follows `translations`, not `outputs`: a language translated or dubbed is billed even if no
output carries it. The project says so in its [`meta.messages`](/vod-express/concepts/projects#messages).

Each `done` file's `usage` in [`GET /projects/{id}/files`](/vod-express/concepts/files#input-files) lists what
it was billed for, entry by entry, with the duration each is billed by.