narrator-ai-cli-skill
Use narrator-ai-cli to create AI-powered movie narration videos through natural language commands
How do I install this agent skill?
npx skills add https://github.com/reason-machines/devtools-skills --skill narrator-ai-cli-skillIs this agent skill safe to install?
- Gen Agent Trust Hubfail
The skill installs and executes a third-party command-line tool from a remote Git repository that is not part of the trusted vendor list. It also processes external movie data and metadata, which presents a surface for indirect prompt injection.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
narrator-ai-cli-skill
Skill by ara.so — Devtools Skills collection.
This skill enables AI agents to use narrator-ai-cli, a command-line tool for automated movie narration video production. The CLI wraps the NarratorAI API and provides commands for searching movies, selecting templates, generating scripts, and composing videos.
What is narrator-ai-cli?
narrator-ai-cli is a Python CLI tool that automates the creation of movie narration videos (also called "film commentary" or "short drama" videos). It handles the entire pipeline: movie selection → template selection → script generation → video composition.
Key capabilities:
- Search ~100 built-in movies or upload custom content
- 90+ narration templates (comedy, suspense, emotional, etc.)
- 146 BGM tracks and 63 dubbing voices
- Two workflows: Adapted Narration (uses existing clips) and Original Narration (AI generates everything)
- Voice cloning and text-to-speech
- Full video composition pipeline
Installation
Install via pip from the GitHub repository:
pip install "narrator-ai-cli @ git+https://github.com/NarratorAI-Studio/narrator-ai-cli.git"
Requirements:
- Python 3.10+
- Dependencies: typer, httpx[socks], httpx-sse, pyyaml, rich
Verify installation:
narrator-ai-cli --version
Configuration
Set API Key
The CLI requires an API key. Set it using the config command:
narrator-ai-cli config set app_key YOUR_APP_KEY
Or set the environment variable:
export NARRATOR_APP_KEY="your_api_key_here"
To obtain an API key: Contact merlinyang@gridltd.com
View Current Configuration
narrator-ai-cli config show
Core Concepts
Before using the CLI, understand these key terms:
- file_id: Unique identifier for uploaded files (movies, audio, images)
- task_id: Identifier for async tasks (script generation, video composition)
- task_order_num: Serial number for tracking task status
- Adapted Narration: Uses pre-existing movie clips (Fast Path)
- Original Narration: AI generates clips from scratch (Standard Path)
- Hot Drama: Select from ~100 built-in movies
- Original Mix: Upload your own movie file
- New Drama: Upload multiple video clips manually
Key Commands
1. Resource Discovery
List movies:
narrator-ai-cli resource movie list
Search for a specific movie:
narrator-ai-cli resource movie list --search "Shawshank"
List narration templates:
narrator-ai-cli resource template list
Filter templates by category:
narrator-ai-cli resource template list --category comedy
List BGM tracks:
narrator-ai-cli resource bgm list
List dubbing voices:
narrator-ai-cli resource dubbing list
2. File Management
Upload a movie file:
narrator-ai-cli file upload /path/to/movie.mp4
Returns a file_id for use in subsequent commands.
List uploaded files:
narrator-ai-cli file list
3. Fast Path: Adapted Narration (Original Narration)
This workflow uses AI to generate the entire video from a movie file.
Step 0: Upload movie (if using Original Mix mode)
narrator-ai-cli file upload movie.mp4
# Output: file_id: abc123
Step 1: Select movie and template
For Hot Drama mode (built-in movie):
narrator-ai-cli resource movie list --search "Inception"
# Note the movie_id
narrator-ai-cli resource template list --category suspense
# Note the template_id
Step 2: Generate narration script
Using Hot Drama mode:
narrator-ai-cli task create-script \
--mode hot_drama \
--movie-id MOVIE_ID \
--template-id TEMPLATE_ID \
--bgm-id BGM_ID \
--dubbing-id DUBBING_ID
Using Original Mix mode (custom movie):
narrator-ai-cli task create-script \
--mode original_mix \
--file-id abc123 \
--template-id TEMPLATE_ID \
--bgm-id BGM_ID \
--dubbing-id DUBBING_ID
Returns task_id and task_order_num.
Step 3: Poll task status
narrator-ai-cli task status TASK_ORDER_NUM
Poll every 10-15 seconds until status is completed. The output will contain script_file_id.
Step 4: Compose video
narrator-ai-cli task compose-video \
--script-file-id SCRIPT_FILE_ID \
--visual-template-id VISUAL_TEMPLATE_ID
Returns task_id and task_order_num for the composition task.
Step 5: Poll composition status and download
narrator-ai-cli task status COMPOSITION_TASK_ORDER_NUM
When completed, the output contains video_url. Download the video:
curl -o final_video.mp4 "VIDEO_URL"
4. Standard Path: Adapted Narration (Adapted Narration)
This workflow uses pre-existing movie clips (requires uploading clip metadata).
Step 0: Upload movie and clip data
narrator-ai-cli file upload movie.mp4
# file_id: movie123
narrator-ai-cli file upload clips.json
# file_id: clips456
Step 1: Generate narration script
narrator-ai-cli task create-script \
--mode new_drama \
--file-id movie123 \
--clip-data-file-id clips456 \
--template-id TEMPLATE_ID \
--bgm-id BGM_ID \
--dubbing-id DUBBING_ID
Steps 2-4: Same as Fast Path (poll script status, compose video, poll composition status)
5. Standalone Tasks
Voice cloning:
narrator-ai-cli file upload voice_sample.mp3
# file_id: voice789
narrator-ai-cli task clone-voice --file-id voice789 --name "My Custom Voice"
Text-to-speech:
narrator-ai-cli task tts \
--text "Hello, this is a test narration." \
--dubbing-id DUBBING_ID \
--speed 1.0 \
--volume 1.0
6. Task Management
List all tasks:
narrator-ai-cli task list
Get task details:
narrator-ai-cli task status TASK_ORDER_NUM
Common Patterns
Pattern 1: End-to-End Video Creation (Fast Path)
# 1. Find a movie
narrator-ai-cli resource movie list --search "Matrix"
# movie_id: 12345
# 2. Find a template
narrator-ai-cli resource template list --category action
# template_id: 67890
# 3. Find BGM and dubbing
narrator-ai-cli resource bgm list
# bgm_id: 111
narrator-ai-cli resource dubbing list
# dubbing_id: 222
# 4. Create script
narrator-ai-cli task create-script \
--mode hot_drama \
--movie-id 12345 \
--template-id 67890 \
--bgm-id 111 \
--dubbing-id 222
# Output: task_order_num: 999
# 5. Poll until complete
narrator-ai-cli task status 999
# Wait 10-15 seconds, repeat until status: completed
# Output contains: script_file_id: script_abc
# 6. Compose video
narrator-ai-cli task compose-video \
--script-file-id script_abc \
--visual-template-id 1
# Output: task_order_num: 1000
# 7. Poll composition
narrator-ai-cli task status 1000
# Wait until status: completed
# Output contains: video_url: https://...
# 8. Download
curl -o my_narration.mp4 "https://..."
Pattern 2: Using Custom Movie (Original Mix)
# 1. Upload movie
narrator-ai-cli file upload my_movie.mp4
# file_id: custom123
# 2. Select template, BGM, dubbing (same as Pattern 1)
# 3. Create script with custom movie
narrator-ai-cli task create-script \
--mode original_mix \
--file-id custom123 \
--template-id 67890 \
--bgm-id 111 \
--dubbing-id 222
# 4-7. Same as Pattern 1
Pattern 3: Batch Video Creation
import subprocess
import json
import time
def create_narration_video(movie_id, template_id, bgm_id, dubbing_id):
# Create script
result = subprocess.run([
"narrator-ai-cli", "task", "create-script",
"--mode", "hot_drama",
"--movie-id", str(movie_id),
"--template-id", str(template_id),
"--bgm-id", str(bgm_id),
"--dubbing-id", str(dubbing_id)
], capture_output=True, text=True)
# Parse task_order_num from output
task_order_num = parse_task_order_num(result.stdout)
# Poll until complete
while True:
status_result = subprocess.run([
"narrator-ai-cli", "task", "status", str(task_order_num)
], capture_output=True, text=True)
status_data = parse_status_output(status_result.stdout)
if status_data["status"] == "completed":
script_file_id = status_data["script_file_id"]
break
elif status_data["status"] == "failed":
raise Exception(f"Script generation failed: {status_data}")
time.sleep(15)
# Compose video
compose_result = subprocess.run([
"narrator-ai-cli", "task", "compose-video",
"--script-file-id", script_file_id,
"--visual-template-id", "1"
], capture_output=True, text=True)
compose_task_num = parse_task_order_num(compose_result.stdout)
# Poll composition
while True:
status_result = subprocess.run([
"narrator-ai-cli", "task", "status", str(compose_task_num)
], capture_output=True, text=True)
status_data = parse_status_output(status_result.stdout)
if status_data["status"] == "completed":
return status_data["video_url"]
elif status_data["status"] == "failed":
raise Exception(f"Video composition failed: {status_data}")
time.sleep(15)
# Create 5 videos with different movies
movies = [101, 102, 103, 104, 105]
for movie_id in movies:
video_url = create_narration_video(
movie_id=movie_id,
template_id=10,
bgm_id=20,
dubbing_id=30
)
print(f"Video for movie {movie_id}: {video_url}")
Configuration Options
The CLI stores configuration in ~/.narrator-ai-cli/config.yaml. Key settings:
app_key: "your_api_key"
api_endpoint: "https://api.narrator-ai.com" # Default, can be overridden
log_level: "INFO"
Set configuration values:
narrator-ai-cli config set KEY VALUE
narrator-ai-cli config set log_level DEBUG
Get configuration value:
narrator-ai-cli config get app_key
Error Handling
The CLI returns standard error codes. Common errors:
| Code | Meaning | Action |
|---|---|---|
| 401 | Invalid API key | Check NARRATOR_APP_KEY or config |
| 404 | Resource not found | Verify file_id, movie_id, or template_id |
| 429 | Rate limit exceeded | Wait and retry |
| 500 | Server error | Check API status, retry later |
Example error output:
Error: API request failed with status 401
Details: {"error": "Invalid API key"}
Troubleshooting
Issue: "narrator-ai-cli: command not found"
Solution: Ensure the CLI is installed and in your PATH:
pip install "narrator-ai-cli @ git+https://github.com/NarratorAI-Studio/narrator-ai-cli.git"
which narrator-ai-cli
Issue: "API key not configured"
Solution: Set the API key:
narrator-ai-cli config set app_key YOUR_KEY
# or
export NARRATOR_APP_KEY="YOUR_KEY"
Issue: Task stuck in "processing" status
Solution: Tasks can take 5-15 minutes depending on complexity. Poll status every 10-15 seconds:
while true; do
narrator-ai-cli task status TASK_ORDER_NUM
sleep 15
done
If stuck for >30 minutes, check API status or contact support.
Issue: Video composition fails
Solution: Ensure script_file_id is from a completed script task. Check task output:
narrator-ai-cli task status SCRIPT_TASK_ORDER_NUM
# Verify status: completed and script_file_id is present
Issue: Downloaded video is corrupted
Solution: Use proper download method:
curl -L -o video.mp4 "VIDEO_URL"
# -L follows redirects
Important Notes for AI Agents
-
Always poll task status — Script generation and video composition are async. Poll every 10-15 seconds until
status: completed. -
Resource IDs are required — Before creating tasks, retrieve IDs for movie, template, BGM, and dubbing from resource commands.
-
Confirm before creating tasks — Each task may incur costs. Ask the user to confirm movie/template selection before running
task create-script. -
Use environment variables for secrets — Never hardcode API keys. Use
$NARRATOR_APP_KEYor config file. -
Handle file uploads carefully — When using Original Mix or New Drama modes, upload files first and note the returned
file_id. -
Visual template is optional — If not specified, defaults to template ID 1. User can override with
--visual-template-id. -
Language chain — If user speaks Chinese, default to Chinese templates, BGM, and dubbing. If English, default to English resources. Always ask for confirmation.
-
Check task status errors — If a task fails, examine the error message in the status output and suggest corrective action.
Workflow Decision Tree
When a user asks to create a narration video:
-
Ask for movie source:
- Built-in movie (Hot Drama) → Get movie_id
- Custom movie file (Original Mix) → Upload file, get file_id
- Multiple clips (New Drama) → Upload files + clip data
-
Ask for template preference:
- List templates, ask user to select by ID or category
-
Ask for BGM and dubbing:
- List options, use defaults if user has no preference
-
Confirm details:
- Show selected movie, template, BGM, dubbing
- Ask "Proceed with video creation?"
-
Execute workflow:
- Fast Path (Original Narration) → Steps 0-4
- Standard Path (Adapted Narration) → Steps 0-5
-
Monitor and report:
- Poll task status, show progress
- Provide video URL when complete
API Endpoint Reference
The CLI communicates with the NarratorAI API at https://api.narrator-ai.com. All requests require the app_key header.
Example manual API call (for debugging):
curl -X GET "https://api.narrator-ai.com/v1/resources/movies" \
-H "app_key: $NARRATOR_APP_KEY"
Data Privacy
- Uploaded files are stored on NarratorAI servers
- Files are associated with your API key
- Generated videos are accessible via temporary URLs
- No data is stored locally by the CLI except configuration
Additional Resources
- CLI Repository: https://github.com/NarratorAI-Studio/narrator-ai-cli
- Resource Preview (Feishu Docs): https://ceex7z9m67.feishu.cn/wiki/WLPnwBysairenFkZDbicZOfKnbc
- Contact: merlinyang@gridltd.com
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/reason-machines/devtools-skills/narrator-ai-cli-skill">View narrator-ai-cli-skill on skillZs</a>