Universal Digital Human Video

Build a privacy-safe, provider-neutral pipeline from source material to a verified MP4. Keep all identity, API, avatar, voice, vault, and output settings outside the skill package.

Start with an option intake

Before producing paid media, collect or infer the following choices. Ask only for missing decisions. If the user explicitly requests full automation, apply the defaults and proceed without repeated confirmation, but never invent credentials, avatar IDs, voice IDs, or consent.

1. Script source
   - provided: use text or a local file supplied by the user.
   - ai: generate a script from a topic, brief, links, or local source material.
   - obsidian: read only the configured Obsidian source folder, compare against an optional output folder to avoid topic duplication, then generate a script.
2. Target length
   - Set seconds or minutes. Default: 60 seconds.
   - Use the configured speaking rate to estimate Chinese length. Start around 3.5–4.5 Chinese characters per second and refine after TTS.
3. Voice mode
   - uploaded_audio: use authorized local audio; skip TTS.
   - preset_tts: use a provider voice.
   - cloned_voice: use a voice ID that the user has lawfully created or is authorized to use.
   - manual: stop after writing the script and provide audio-generation instructions.
4. Digital-human mode
   - Use an existing authorized avatar ID, a user-provided source video, or manual generation.
   - Never clone or impersonate a real person without authorization.
5. Watermark policy
   - platform_default (default): preserve the provider's compliance watermark.
   - enabled: request a visible compliance watermark.
   - disabled_if_allowed: disable only when the provider permits it and applicable rules allow it.
   - Never remove a legally or contractually required watermark.
6. Packaging
   - none: deliver the digital-human source video after verification.
   - subtitles: add corrected subtitles only.
   - hyperframes: add subtitles, knowledge cards, transitions, and optional camera motion.
7. Visual style
   - warm-gray-knowledge (default): warm gray translucent cards, restrained orange/teal accents, calm motion, bottom safe-area subtitles.
   - auto: inspect the scene, speaker position, negative space, topic, and brand cues; select a readable style.
   - custom: follow user colors, typography, card density, motion intensity, aspect ratio, and brand assets.

Use config.example.json as the decision checklist. Validate it with:

python3 scripts/skill_cli.py validate-config --config config.json

Credential and identity setup

Read references/provider-setup.md before any provider call.

• Require users to create their own digital-human and TTS accounts.
• Load API credentials only from environment variables or a user-private secret store.
• Keep avatar IDs and voice IDs in private configuration, preferably referenced through environment-variable names.
• Never put real credentials, names, IDs, source notes, signed download URLs, or local personal paths in the skill, repository, logs, screenshots, examples, or final response.
• Run doctor before paid work:

python3 scripts/skill_cli.py doctor --config config.json

If a provider adapter is unavailable, read references/adapter-contract.md, inspect the provider's official documentation, and implement the adapter in the user's private workspace rather than committing account-specific code to this skill.

Workflow

1. Create a private project folder

Keep inputs, generated media, task state, and provider adapters outside the installed skill directory. Copy config.example.json to the project folder as config.json, then fill only non-secret settings. Add the project folder to ignore rules when it may contain private material.

2. Prepare the script

For provided, preserve meaning unless rewriting is requested.

For ai, define audience, topic, point of view, call to action, language, tone, and target duration. Prefer natural spoken phrasing, varied sentence length, concrete examples, and an identifiable point of view. Avoid generic headings, repetitive transitions, unsupported statistics, and promotional filler.

For obsidian:

1. Require an explicit vault or source-folder path in the private project config.
2. Read only that folder; never recursively scan the entire home directory.
3. Prefer user-authored or user-approved notes when metadata distinguishes them.
4. Optionally inspect the configured output folder to reject overlapping topics.
5. Preserve original notes; write the generated script to the configured output folder only when requested.
6. Do not publish note content, vault paths, filenames, or metadata to the public repository.

Estimate the draft duration:

python3 scripts/skill_cli.py estimate --text-file script.txt --chars-per-second 4.0

3. Generate or obtain narration

Follow the selected voice mode. For cloned voices, require an explicit confirmation that the user owns the voice or has permission. Use clean reference audio and follow the provider's consent and disclosure requirements.

Generate narration once, probe its exact duration, and revise the script only when the duration falls outside the configured tolerance. Do not repeatedly call paid APIs without diagnosing the mismatch.

4. Generate the digital human

Validate the configured avatar before submission. Save a state file immediately after receiving a task ID, excluding secrets and signed URLs. Poll or resume the same task instead of creating duplicates. Download successful results promptly because provider URLs may expire.

Preserve the user's watermark choice subject to platform and legal requirements. Record only the boolean/policy choice, never account data.

5. Package the video

For none, skip directly to verification.

For subtitles, transcribe the final video audio. When the approved script is available, align approved script characters to ASR word/character timestamps so displayed text stays correct while timing follows the actual audio.

For hyperframes, read references/hyperframes-styles.md. Probe media first, create a privacy-clean Rec.709 seek-friendly proxy, inspect representative frames, identify the face-safe region and negative space, then build deterministic subtitles and cards.

Default style rules:

• Preserve the speaker, narration, and scene.
• Place cards in measured negative space; never cover the face or mouth.
• Use the warm-gray knowledge-card style unless auto or custom is selected.
• Keep major cards readable for roughly 6–12 seconds.
• Keep camera push-in subtle, normally below 1.025.
• Use a single deterministic paused timeline and hard-hide subtitles at their end times.
• On memory-constrained machines, use one worker, source-matched frame rate, SDR for SDR media, and a dense-keyframe H.264 proxy.

6. Verify privacy and media

Run:

python3 scripts/skill_cli.py verify-media --file output.mp4
python3 scripts/skill_cli.py scan-public --path .

Confirm a non-empty video stream, an audio stream, plausible duration, intended dimensions and frame rate, no black tail, readable subtitles/cards, no face obstruction, and no private metadata. Strip optional container metadata with a local FFmpeg remux when appropriate; do not alter required provenance or compliance signals.

7. Deliver

Deliver the final MP4 and, when requested, the script, transcript, storyboard, effect plan, and private project folder. Report provider/task status, duration, dimensions, frame rate, and verification result without exposing credentials or personal identifiers.

Non-negotiable safeguards

• Obtain authorization for every face, avatar, voice, source video, and note used.
• Do not create deceptive impersonation, fraud, harassment, or undisclosed harmful synthetic media.
• Do not commit .env, secret stores, private configs, task states, notes, audio, avatar media, signed URLs, or generated videos to the public repository.
• Do not silently disable provider compliance features.
• Do not overwrite source notes or source media.
• Do not start paid API calls until configuration validation and consent checks pass.