SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsopenstoryline-use

openstoryline-use

Agents & models

View repository

Updated 10-15 21:42

About this skill

OpenStoryline Usage Skill

You are responsible for executing the actual editing workflow of OpenStoryline under the premise of "installation completed". OpenStoryline is an editing Agent that allows users to edit videos through natural language conversation using their own materials. It has built-in features such as material search, content understanding, subtitle generation, and text-to-speech, and users can provide specific editing/modification suggestions multiple times.

The goal is: using existing scripts, stably complete a closed loop from starting the service to producing a video; and support continuing the conversation, performing secondary edits, and regenerating new videos on the same session_id .

Scope

This skill only handles "usage and editing":

  1. Check and modify the necessary fields of config.toml .
  2. Start the MCP server.
  3. Start uvicorn agent_fastapi:app。
  4. Create a session and send an editing request.
  5. Wait for and verify the output video artifact.
  6. Continue the conversation on the same session_id and perform secondary edits.
  7. Verify whether a new output_*.mp4。

Do not handle the complete installation process (dependency installation, model download, resource download, etc.); that is the scope of the installation skill. If you encounter problems during startup and suspect it is an installation issue, then go check the installation Skill openstoryline-install

Core Rules

  1. By default, only listen on 127.0.0.1, do not actively expose it to the LAN.
  2. Prefer reusing existing scripts; do not reinvent the wheel:
    • Configuration modification script: located in the code repositoryscripts/update_config.py
    • The Web service bridge script is located in the current skill directory at scripts/bridge_openstoryline.py. Please first locate the current skill directory, then concatenatescripts/bridge_openstoryline.py
  3. Long-running services (MCP / Web) must be started as "long-running processes" and logs must be continuously observed; do not treat the startup command as a one-time probe command.
  4. Do notappend these wrappers after the startup command:
    • | head
    • | tail
    • grep
    • timeout
    • sleep
    • pkill
    • as well as other wrappers that truncate logs, exit early, or forcibly kill processes
  5. Ask the user which materials need to be edited and their paths.
  6. The session_id returned after creating the session in the first round must be saved; subsequent conversation continuation and secondary edits all depend on it.
  7. If the server prompts "the previous message has not yet completed, please send again later", do not create a new session; prefer to wait, and if necessary only terminate the stuck local bridge process, then continue reusing the original session_id to retry.
  8. Do not actively terminate the MCP / Web service in the middle of task execution unless the user explicitly requests stopping, or the service itself has been confirmed to be inactive.
  9. After each task is completed, you must clearly return to the user:
    • session_id
    • Final video .mp4 full path
    • If there are secondary edits, also explain whether a new output file was generated
  10. The example commands below all usesource .venv/bin/activateas an example; you need to replace them with the correct commands according to the environment the user actually uses (for exampleconda activate ）。
  11. If the port is occupied, prefer switching to another port.

OpenClaw Execution Strategy (Important)

If you are OpenClaw, be sure to note the following key points:

How to run long-running services

For the following two types of commands:

  • PYTHONPATH=src python -m open_storyline.mcp.server
  • uvicorn agent_fastapi:app --host 127.0.0.1 --port 8005

They must be handled as "long-running processes":

  1. Use exec to start, and enable PTY (if the tool supports pty: true, enable it).
  2. After startup, do not immediately judge it as a failure; MCP Server startup takes several minutes.
  3. Use process poll / process log to continuously observe the returned content. Do not be in a hurry to kill the process.
  4. Only continue to the next step after seeing the success log.

How to run one-off commands

The following commands are suitable for ordinary one-off exec：

  • Modify config.toml
  • create a session
  • on the existing session_id continue the conversation
  • Find .mp4
  • View file size

Observe which log is most useful

In actual testing,Web service logs are the most suitable for checking editing progress.
Common normal process milestones include:

  • filter_clips
  • group_clips
  • generate_script
  • generate_voiceover
  • render_video

If the bridge script is still waiting, it does not mean the system is not working; it may just be that the server side is still processing.

Standard Workflow (OpenClaw)

0) Confirm the repository root directory

In subsequent commands, <repo-root> points to the OpenStoryline repository root directory, for example:

/Users/yourname/Desktop/code/Openstoryline/FireRed-Openstoryline

All commands are by default executed in this directory, and the environment is activated first.

1) Enter the project root directory and configure

Required configuration

Before starting editing, the following 6 fields must have values, otherwise model calls will fail. You must first ask the user for the specific values of these fields, then use a script to modify them:

  • [llm].model
  • [llm].base_url
  • [llm].api_key
  • [vlm].model
  • [vlm].base_url
  • [vlm].api_key

Directly usable commands (execute in the repository root directory, using .venv as an example):

cd <repo-root> && source .venv/bin/activate && python scripts/update_config.py --config ./config.toml --set llm.model=REPLACE_WITH_REAL_MODEL
cd <repo-root> && source .venv/bin/activate && python scripts/update_config.py --config ./config.toml --set llm.base_url=REPLACE_WITH_REAL_URL
cd <repo-root> && source .venv/bin/activate && python scripts/update_config.py --config ./config.toml --set llm.api_key=sk-REPLACE_WITH_REAL_KEY

cd <repo-root> && source .venv/bin/activate && python scripts/update_config.py --config ./config.toml --set vlm.model=REPLACE_WITH_REAL_MODEL
cd <repo-root> && source .venv/bin/activate && python scripts/update_config.py --config ./config.toml --set vlm.base_url=REPLACE_WITH_REAL_URL
cd <repo-root> && source .venv/bin/activate && python scripts/update_config.py --config ./config.toml --set vlm.api_key=sk-REPLACE_WITH_REAL_KEY

Optional configuration

The following are common optional items. Set them as needed:

1. MCP port (when there is a port conflict)
cd <repo-root> && source .venv/bin/activate && python scripts/update_config.py --config ./config.toml --set local_mcp_server.port=8002
2. Material search (Pexels)
cd <repo-root> && source .venv/bin/activate && python scripts/update_config.py --config ./config.toml --set search_media.pexels_api_key=REPLACE_WITH_PEXELS_KEY
3. TTS (if voiceover is needed)

Choose one of the following 3 providers and fill it in:

# minimax
cd <repo-root> && source .venv/bin/activate && python scripts/update_config.py --config ./config.toml --set generate_voiceover.providers.minimax.base_url=https://api.minimax.chat/v1/t2a_v2
cd <repo-root> && source .venv/bin/activate && python scripts/update_config.py --config ./config.toml --set generate_voiceover.providers.minimax.api_key=REPLACE_WITH_MINIMAX_KEY

# bytedance
cd <repo-root> && source .venv/bin/activate && python scripts/update_config.py --config ./config.toml --set generate_voiceover.providers.bytedance.uid=REPLACE_UID
cd <repo-root> && source .venv/bin/activate && python scripts/update_config.py --config ./config.toml --set generate_voiceover.providers.bytedance.appid=REPLACE_APPID
cd <repo-root> && source .venv/bin/activate && python scripts/update_config.py --config ./config.toml --set generate_voiceover.providers.bytedance.access_token=REPLACE_ACCESS_TOKEN

# 302
cd <repo-root> && source .venv/bin/activate && python scripts/update_config.py --config ./config.toml --set generate_voiceover.providers.302.base_url=https://REPLACE_BASE_URL
cd <repo-root> && source .venv/bin/activate && python scripts/update_config.py --config ./config.toml --set generate_voiceover.providers.302.api_key=REPLACE_API_KEY

2) Start MCP Server

Note that starting the MCP Server may take several minutes. Be sure to wait patiently and do not rush to kill the process. macOS/Linux:

cd <repo-root> && source .venv/bin/activate && PYTHONPATH=src python -m open_storyline.mcp.server

Windows:

cd <repo-root>
. .venv\Scripts\Activate.ps1
$env:PYTHONPATH="src"
python -m open_storyline.mcp.server

Seeing logs similar to the following is considered success:

Uvicorn running on http://127.0.0.1:8001

3) Start the Web service (uvicorn)

macOS/Linux:

cd <repo-root> && source .venv/bin/activate && uvicorn agent_fastapi:app --host 127.0.0.1 --port 8005

Success is indicated by the following logs:

INFO:     Started server process [PID]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8005 (Press CTRL+C to quit)

4) Create an editing session

Note to replace the address with the actual address from when the Web service was started in the previous step.

curl -s -X POST "http://127.0.0.1:8005/api/sessions"

This step will create an editing session and obtain asession_id，very important! As long as the Web service is still alive, you can use thissession_idto upload materials and conduct multi-turn conversations. Be sure to keep it.

5) Upload materials

Option 1:

curl -s -X POST "http://127.0.0.1:8005/api/sessions/{session_id}/media" -F "files=@/absolute/path/input.mp4"

Option 2: For large files, it is recommended to use local copy directly

cp path/to/source.mp4 <repo-root>/outputs/{session_id}/media

6) Start the editing conversation (automatically create a session)

Use the bridge script included with the Skill.

  • skills-root: the directory where the current skill is located.
  • session-id: enter the session_id
  • base-url enter the url of the Web service
  • prompt the user's editing requirements
  • lang the language type used by the user. Currently only zh / en are supported. Set it once.
cd <repo-root> && source .venv/bin/activate && python <skills-root>/scripts/bridge_openstoryline.py \
  --session-id <session_id> \
  --base-url http://127.0.0.1:8005 \
  --prompt "剪一个小红书风格视频" \
  --lang "zh"

7) Wait and observe the editing progress

Sometimes the editing Agent will first ask about the editing requirements; sometimes it will start editing directly. Editing may take several minutes, especially when there is copy, voiceover, or rendering.

Correct approach

  1. Continuously poll the process session corresponding to the current bridge script.
  2. At the same time, check the Web service logs. The editing Agent will update its progress in real time.
  3. As long as the Web service logs are still advancing, continue waiting and do not casually restart the service.

Practical experience

If the bridge command has not returned yet, but the Web service logs show nodes are already running, this usually means the server is still working normally; do not misjudge it as a failure.

8) Second round: continue chatting in the same session

Based on the assistant's reply, continue sending editing requests to it. For example, the assistant has made an editing plan and is asking for confirmation. Then:

cd <repo-root> && source .venv/bin/activate && python <skills-root>/scripts/bridge_openstoryline.py \
  --base-url http://127.0.0.1:8005 \
  --session-id <上一步session_id> \
  --prompt "开始剪辑"

Or adjustments are needed:

cd <repo-root> && source .venv/bin/activate && python <skills-root>/scripts/bridge_openstoryline.py \
  --base-url http://127.0.0.1:8005 \
  --session-id <上一步session_id> \
  --prompt "使用欢快的BGM"

9) Check the first-round output

Generally, the editing agent's output will directly include the path to the editing output. If not, check in this order:

cd <repo-root> && find .storyline/.server_cache/<session_id> -name "output_*.mp4" 2>/dev/null

Criteria

Having output_*.mp4 is considered a successful edit.

10) Send the video

Send the generated video to the user for viewing and ask for their feedback.

Video sending guide for the OpenClaw + Feishu APP scenario

If you are OpenClaw and the user is using the Feishu APP on a phone, use the following dedicated guide. Requirements:

  • Python 3.6+
  • Installed requests 
    python3 -m pip install requests
  • OpenClaw has the Feishu channel configured

An example script run is as follows; this script will automatically read the Feishu credentials from ~/.openclaw/openclaw.json. Choice of receive-id

  • oc_xxx -> chat_id: send to a group chat or the current one-on-one chat session; recommended first
  • ou_xxx -> open_id: send to a specified user
  • on_xxx -> user_id: use only when it is clear that what you have is a user_id
cd <repo-root> && source .venv/bin/activate && python <skills-root>/scripts/feishu_file_sender.py --help
cd <repo-root> && source .venv/bin/activate && python <skills-root>/scripts/feishu_file_sender.py --file /absolute/path/to/video.mp4 --receive-id-type chat_id --receive-id oc_xxx

11) Secondary editing

In the case where a video has already been generated, if the user is not satisfied with the video content,you can reuse the same session_id to continue modifying the video, and generate a new output_*.mp4。

Example: modify the copy style

cd <repo-root> && source .venv/bin/activate && python <skills-root>/scripts/bridge_openstoryline.py \
  --base-url http://127.0.0.1:8005 \
  --session-id <session_id> \
  --prompt "帮我把文案换成更欢乐、更有活力的风格"
  • Under the same session_id , the system will rerun the corresponding nodes, and then rerender.
  • Under the same session_id , a new render_video_* directory will appear.
  • A new output_*.mp4。

Security Note

Only when the user explicitly requests mobile / LAN access, switch to --host 0.0.0.0。
Also remind: use only on trusted networks, and avoid exposing it to public networks.