::adom-video{video="/OWNER/SLUG/render/videos/demo.mp4" title="How we built it" poster="/OWNER/SLUG/render/videos/poster.jpg" captions="/OWNER/SLUG/render/videos/captions.vtt" chapters="/OWNER/SLUG/render/videos/chapters.json"}

::adom-video{src="/OWNER/SLUG/render/videos/demo.video.json"}

{
  "video": "/OWNER/SLUG/render/videos/demo.mp4",
  "title": "How we built it",
  "poster": "/OWNER/SLUG/render/videos/poster.jpg",
  "chapters": [{"t": 0, "title": "The design"}, {"t": 12.5, "title": "The test"}],
  "captions": "WEBVTT\n\n00:00:00.200 --> 00:00:03.100\nThe exact spoken sentence.\n"
}

ffmpeg -hide_banner -i final.mp4 -vn -af silencedetect=noise=-38dB:d=0.7 -f null -

const player = document.querySelector('adom-video');
await player.adomDrive.ready();
player.adomDrive.state(); // duration, chapters > 0, captions > 0, playback state

---
name: wiki-video-captions
description: >-
  Narrated ::adom-video in a README with WebVTT captions and chapters. Part of
  adom-wiki-skillpack.
---

# Wiki video and caption delivery

Use the existing page and the registered **::adom-video** widget. Do not create a
separate video page or hand-written HTML player. Read **demo-video-publishing**
(`adom-wiki pkg install adom/demo-authoring-skillpack` ships it) for production/editing and **adom-tts** for narration. This skill covers the
README delivery path, including existing videos with no caption sidecar.

## Find and embed the supported widget

Read `https://wiki.adom.inc/api/widgets` for the live `adom-video` attributes.
Put the tag on its own line outside a code fence. Use absolute wiki render paths.
`video=` takes media; `src=` takes a JSON manifest, never an MP4.

```markdown
::adom-video{video="/OWNER/SLUG/render/videos/demo.mp4" title="How we built it" poster="/OWNER/SLUG/render/videos/poster.jpg" captions="/OWNER/SLUG/render/videos/captions.vtt" chapters="/OWNER/SLUG/render/videos/chapters.json"}
```

When asked to lead with the film, put the widget immediately after the README
title, before the technical overview. Preserve a plain download link. Do not
change the page's visibility or autoplay sound. Do not use raw `<video>` merely
because it is familiar: that loses the standard player controls and delivery
contract. A raw tag is a fallback only for a verified unsupported surface.

Prefer the manifest form, especially for private pages:

```markdown
::adom-video{src="/OWNER/SLUG/render/videos/demo.video.json"}
```

```json
{
  "video": "/OWNER/SLUG/render/videos/demo.mp4",
  "title": "How we built it",
  "poster": "/OWNER/SLUG/render/videos/poster.jpg",
  "chapters": [{"t": 0, "title": "The design"}, {"t": 12.5, "title": "The test"}],
  "captions": "WEBVTT\n\n00:00:00.200 --> 00:00:03.100\nThe exact spoken sentence.\n"
}
```

The wiki inlines the JSON. Inlining chapter rows and WebVTT text avoids separate
unauthenticated fetches from its opaque widget sandbox. Do not expose a private
file or weaken CSP to fix caption fetches. Keep separate downloadable `.vtt` and
`.srt` files alongside the manifest for reuse.

## Generate real captions against the final edit

1. Identify the exact final media hash and duration. Caption the actual voice,
   not headings, visual labels, or an earlier draft script.
2. For TTS, reuse the source narration text and audio files. Prefer timestamped
   word/sentence metadata from the synthesis tool when available. **gang-takes**
   in `adom/adom-video-post` emits VTT, chapters, and widget embeds; inspect its
   output rather than assuming it reflects a later edit.
3. If timestamps are absent, align the known script to the final audio with a
   speech aligner or word-timestamp ASR. For unknown speech, transcribe first.
   Review technical names, units and numerals against the audio and source.
   Do not replace accurate written part names with recognition mistakes.
4. A single-sentence audio clip can use its measured placement and spoken end.
   A multi-sentence clip needs sentence/phrase boundaries. Do not assign every
   sentence the whole clip interval or stretch a paragraph across a scene.
   Even word-count timing is only an estimate; label it and inspect playback.
5. Write UTF-8 WebVTT with `WEBVTT`, a blank line, then `HH:MM:SS.mmm -->
   HH:MM:SS.mmm` and text. SRT uses numbered cues and comma milliseconds.
   Prefer one or two readable lines, roughly 42 characters per line, natural
   phrase breaks, and a few seconds per cue. Preserve all spoken words.
6. Verify finite, increasing timestamps, positive cue lengths, no unintended
   overlaps, and cue/chapter ends within the measured media duration. Chapters
   are JSON `[{"t": seconds, "title": "..."}]`, sorted and starting at zero.
7. Any trim, narration delay, time stretch, concatenation, or speed change
   invalidates old timing. Regenerate or map captions AND chapters through the
   edit decision list. Keep the original cut and record source/output hashes.

## Remove padded dead air without damaging speech

Measure before editing, for example:

```bash
ffmpeg -hide_banner -i final.mp4 -vn -af silencedetect=noise=-38dB:d=0.7 -f null -
```

These are starting thresholds, not universal speech detectors. Music may conceal
silent narration; analyze the isolated voice too when available. Review flagged
intervals. Preserve quiet consonants, breaths and natural sentence pauses. Trim
padding or shorten the corresponding picture; keep important action visible by
appropriate retiming. Do not fill time with invented narration, freeze frames,
or slow the voice solely to meet a target runtime. If tightening changes runtime,
say so. Recheck the FINAL encoded audio at scene joins and ending. A silent audio
track is not a narration pass; a loudness check is not a comprehension review.

## Publish and prove the real player

Push README, media, poster, VTT/SRT, chapters and manifest using `adom-wiki repo
push --files ...`. Reuse the intended Pup tab and inspect the rendered README.
Do not confuse a successful download with a working widget.

Target the iframe whose URL contains `/widget/adom-video`. Through Pup's frame
selector, evaluate:

```javascript
const player = document.querySelector('adom-video');
await player.adomDrive.ready();
player.adomDrive.state(); // duration, chapters > 0, captions > 0, playback state
```

The widget is sandboxed: direct parent DOM access can fail legitimately. Use the
browser's frame-targeted evaluation; never loosen the sandbox. Mute temporary
playback checks (`player.v.muted = true`), seek into beginning/middle/end cues,
turn captions on, inspect rendered caption text and time progression, then pause
and restore the prior mute preference. Screenshot the actual README widget.
Never claim the user heard a muted check. Do not leave playback running.

A package source push is not a release. Skillpack changes also need the explicit
package file list, install/uninstall entries, root routing, discovery triggers,
pack inspection and a tested version publication. Existing AI threads must read
updated skills; installing files does not replace their already-loaded context.