how-to-use-media-arneis

name	how-to-use-media-arneis
description	Guides AI agents in running, updating, and writing specs for the media-arneis orchestration harness.
version	0.2.9

Skill: Using and Maintaining media-arneis

This skill equips you to work with the Arneis media orchestration harness. Arneis uses declarative YAML files to model media projects, executing tasks (video, image, audio generation, and assembly) concurrently using Ruby Fibers.

---

🎯 Intended Workflows

As an AI agent, you will typically perform the following activities:

1. Pitch / Ideation: Translate a raw creative research document into a structured project YAML.
2. Execution / Orchestration: Execute the YAML plan, monitor its progress, and handle polling or failures.
3. Character Management: Create or edit character bios to maintain visual consistency.
4. Resilience & Restarting: Safely resume interrupted media projects by inspecting and resolving issues in .state.yaml.
5. Quality Criticism: Understand and address criticisms generated by the LLM-as-a-Judge evaluations.

---

🛠️ Commands Reference

Always invoke commands from the project root using bundle exec or just wrappers.

Task	Command	Description
Research & Pitch	just arnectl research-pitch <markdown_path>	Generates a project YAML from a markdown research text.
Apply / Run Spec	just arnectl apply <yaml_path>	Parses a project YAML, creates output structure, and starts task runner.
Force Clean Run	just arnectl apply <yaml_path> --force-clean	Discards previous state and starts execution from scratch.
Check Project Status	just arnectl status <output_dir>	Shows a detailed breakdown of scenes, tasks, evaluations, and costs.
Verify Media Outputs	just arnectl verify <output_dir>	Performs technical validation of generated files (formats, codecs, durations).
Generate Portrait	just arnectl generate CharacterImage -c <name> -p "<prompt>"	Generates a consistent portrait of the specified character.
Render Dependencies	just arnectl graph <yaml_path>	Renders a Mermaid.js flowchart of the execution tasks.

---

📄 Project Kinds & Specifications

Arneis uses Kubernetes-style custom resource YAML specs. Ensure the YAMLs you generate have apiVersion, kind, metadata, and spec sections.

1. VideoProject

• Purpose: Generates scene videos (Veo), theme audio (Lyria), and stitches them via ffmpeg.
• Spec Fields: project_title, output_filename, scenes (list of scene and description), background_music (with prompt property).

2. KidsStory

• Purpose: Produces illustrated storybooks.
• Workflow: Enhances illustration prompts, expands chapter narrative texts, translates into target languages, runs text-to-speech (Chirp), and concatenates page audio into local audiobooks.
• Spec Fields: story_title, character_id, story_audio (target languages list), pages (list of page, description, and text), background_music.

3. CharacterImage

• Purpose: Creates single or multi-character portraits/scenes.
• Spec Fields: project_title, characters (list of IDs), prompt, aspect_ratio (e.g. 16:9).

4. ComicStrip

• Purpose: Multi-row panel-by-panel comic layout.
• Spec Fields: title, rows (containing row_number and a list of panels with panel_number, description, and dialogue).

5. PowerColon

• Purpose: Compiles slides into PowerPoint presentation decks (.pptx).
• Spec Fields: presentation_title, slides (containing title, bullets, and illustration details).

---

👤 Character Consistency & Profiles

Character records are loaded from data/characters/<id>/character.yaml.

• Character Bio: When generating images involving a character, read their visual_look and personality and incorporate relevant descriptions in the image generator prompts.
• Consistency Images: Reference photos in the character's folder are automatically read and sent as image-to-image/reference seeds to Imagen.
• Feedback Retries: If character evaluations fail consistency scores, append a feedback node inside your YAML spec with the path to the previous image and specific critique comments, then re-apply.

---

🔄 Resilience & State Tracking

Every execution run populates a .state.yaml file inside the output directory.

• Prior to creating assets, check the state file to see which components are marked done or verified.
• Do not regenerate completed assets unless explicitly instructed or if running with --force-clean.
• Polling states are maintained here for long-running asynchronous API jobs (like video creation). Ensure you check operation IDs for tasks marked polling.

---

⚠️ Preventing Documentation Drift

This skill file and the USER MANUAL.md are bound to the repository version to prevent drift:

• The system checks that the version field in this file's frontmatter matches the contents of the VERSION file.
• It also checks that the version line in docs/USER MANUAL.md matches.
• A unit test runs under just test to enforce this constraint.
• Agent Instruction: If you increment the system version in the VERSION file, you MUST simultaneously update the version in:
  1. This SKILL.md file (the version: metadata in frontmatter).
  2. docs/USER MANUAL.md (the version block at the top).