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.

​
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 and Configure a project.

​
The folders

Each project has its own place in SyncWords’ S3 storage, given in its storage field:
  • 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 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.

​
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: it is called when a file is done or failed and when a project stops. Or poll the listing, as described in 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. Each done file’s usage in GET /projects/{id}/files lists what it was billed for, entry by entry, with the duration each is billed by.