dpp-pipeline

Use when you need to turn a local source video and one product image into a single-product placement video with the DPP pipeline.

Security Scan

The skill's requests, scripts, and code are coherent with its stated purpose (creating a single-product placement video) and its required credential (ARK_API_KEY); no obvious misdirection or unrelated privilege requests were found.

Purpose & Capability

Name, description, and runtime code all implement a DPP storyboard/placement/compose/final-cut pipeline. Required binaries (python3, ffmpeg), the primary env var (ARK_API_KEY), and optional TOS credentials align with the documented behavior (uploading media to Ark, optionally uploading reference media to TOS).

Instruction Scope

SKILL.md and the stage scripts confine operations to the caller workspace (or DPP_WORKDIR) and describe the exact workflow. The runtime reads a workspace .env for Ark/TOS configuration, uploads media to Ark, and may upload reference media to TOS when requested — these actions are consistent with the stated purpose. There are no instructions to read unrelated system files or exfiltrate data to unknown endpoints.

Install Mechanism

The registry has no formal install spec, but the bundled scripts bootstrap a Python virtualenv and pip-install dependencies from PyPI (runtime/pyproject.toml includes 'tos' and 'volcengine-python-sdk[ark]'). This is expected for a Python-based tool but means network access to PyPI is used during bootstrap and packages will be installed on the host.

Credentials

The only declared required env var is ARK_API_KEY (primary credential) which the code uses. TOS_* variables are read as optional configuration when auto-upload is enabled. The runtime intentionally loads a workspace .env (via DPP_DOTENV_PATH) — users should avoid placing unrelated secrets in that file.

Persistence & Privilege

always is false and the skill does not request persistent platform privileges. Bootstrap creates a local .venv under the skill directory; scripts and code do not modify other skills or system-wide agent settings.

Assessment

This skill appears to do what it claims: it uploads local media to Ark (required) and can optionally upload reference media to a TOS bucket if TOS credentials are provided. Before installing/running: (1) provide only a dedicated workspace directory and avoid placing unrelated secrets in its .env (the skill will load that file); (2) be aware scripts will create a local .venv and pip-install packages from PyPI (network activity during bootstrap); (3) do not run this on sensitive videos you don't want uploaded to Ark/TOS; (4) if you require higher assurance, inspect runtime/src/dpp_storyboard/ark_client.py and compose/upload paths and test in an isolated environment. Overall the required binaries, env vars, and network behavior are proportionate to the stated purpose.

Run the DPP storyboard, placement, and compose-best flow from a local workspace.

The skill bundles its Python runtime under runtime/, but it does not treat the installed skill directory as the project workspace. Inputs and outputs live under the caller's current working directory by default. Override that with DPP_WORKDIR when needed.

When to Use

• Generate storyboard.json from a local video with dpp-storyboard.
• Generate a single-product material config from one product image under assets/.
• Select the best storyboard segment for one product image with dpp-placement.
• Run the final best-segment composition flow with dpp-compose-best.
• Replace the best segment in the original video with the generated clip using dpp-final-cut.

Do not use this skill for multi-product batch processing. This skill handles one local video and one product image at a time.

Dependencies

• Python 3.11+
• ffmpeg
• Network access to Ark and TOS
• Ark environment variables in the target workspace .env
• TOS_BUCKET, TOS_AK, TOS_SK, TOS_ENDPOINT, and TOS_REGION when compose-best must auto-upload the reference clip or image
• TOS_OBJECT_PREFIX, TOS_ENABLE_HTTPS, and TOS_FORCE_ENDPOINT are optional TOS tuning variables

Install Python dependencies by running:

scripts/bootstrap_runtime.sh

Workspace Layout

The runtime lives inside the installed skill. The caller workspace holds inputs, configs, logs, and outputs:

<workspace>/
  .env
  assets/
    <single product image>
  video/
    demo.mp4
  configs/
    placement_material.json
  log/
  output/
    <video_stem>/
      finalCut/

Initialize a new workspace with:

scripts/init_workspace.sh

That command creates assets/, video/, configs/, and output/, and copies sample files into place.

Workflow

1. Run scripts/bootstrap_runtime.sh.
2. If the target workspace is empty, run scripts/init_workspace.sh.
3. Ensure the workspace .env contains Ark credentials and defaults.
4. Ensure video/demo.mp4 exists before storyboard, unless the user will pass --video.
5. Ensure assets/ contains exactly one product image before material generation, unless the user will pass --image.
6. Run scripts/run_storyboard.sh.
7. Run scripts/run_generate_material.sh.
8. Run scripts/run_placement.sh.
9. Run scripts/run_compose_best.sh.
10. Run scripts/run_final_cut.sh.

Do not skip stage ordering unless the user explicitly asks to reuse an existing artifact.

Review Pauses

Do not pause by default.

• If the user wants review pauses, stop after each requested stage and report the artifact path.
• If the user asks to continue, move directly to the next stage when the required inputs already exist.
• If the user asks to rerun a later stage, reuse earlier artifacts unless the input changed.

Typical checkpoints:

• After storyboard: review segmentation quality and thumbnail coverage.
• After placement: review best_segment_index, ranking, and placement rationale.
• After compose-best: review composition_result.json, prompt quality, and reference-media URL status.
• After final-cut: review finalcut_result.json and verify the output video at output/<video_stem>/finalCut/final_cut.mp4.

Execution Rules

• Run the stage scripts from the caller workspace, or set DPP_WORKDIR to the target workspace path.
• Keep the installed skill directory immutable except for .venv/ and the generated runtime/ bundle.
• Always bootstrap the runtime before the first stage command.
• dpp-storyboard, dpp-placement, and dpp-compose-best can each take more than 10 minutes. Do not assume the process is hung just because it is quiet for a while; warn the user that the stage is long-running and let it complete naturally.
• After each stage, report the main artifact path.
• Before compose-best auto-upload, verify TOS_BUCKET, TOS_AK, TOS_SK, TOS_ENDPOINT, and TOS_REGION if the user did not provide --reference-video-url or DPP_REFERENCE_VIDEO_URL.
• This skill sends prompts and media metadata to Ark. Compose-best may also upload the reference clip and product image to TOS.

Detailed commands live in references/commands.md.

Scripts

• scripts/bootstrap_runtime.sh
• scripts/init_workspace.sh
• scripts/run_storyboard.sh
• scripts/run_generate_material.sh
• scripts/run_placement.sh
• scripts/run_compose_best.sh
• scripts/run_final_cut.sh

Each script forwards all CLI arguments to the underlying Python module.