---
name: seriflow
description: macOS の動画編集アプリ Seriflow を、起動中のアプリの外部AI連携（MCP）から操作する手引き。セリフ単位・シーン単位の解説動画の編集（字幕の見た目、セリフの取り込みと並べ替え、立ち絵、背景、文字や図形、演出、BGM・SE、確認用の画像と書き出しの準備）を、利用者の画面と同じ操作で行う。利用者が Seriflow の作品を AI に編集させたいときに使う。
---

# Seriflow

Seriflow は利用者の Mac で動いているアプリで、作品は利用者の画面に開いている。AI は画面と同じ編集を
外部AI連携（MCP）経由で当てる。編集は利用者の ⌘Z で1手ずつ戻せるので、AI は作品を壊す心配より
「利用者がいま見ているものと食い違わないこと」を優先する。Seriflow の外部AI連携に API の従量課金は無い。

## 準備

1. 利用者に Seriflow を起動してもらい、メニューの「共通設定」→「管理」→「外部AI連携（MCP）」をオンにしてもらう。
   モードは「読み取り専用」「プロジェクトの編集を許可」「すべての操作を許可」の3つ。編集を頼まれたら
   2つ目以上が要る。モードを AI 側から変える方法は無い。
2. 画面に出る `http://127.0.0.1:PORT/mcp` を MCP サーバーとして登録する。認証は無い。ポートは一度決まると変わらない。

Claude Code:

```bash
claude mcp add --transport http seriflow http://127.0.0.1:PORT/mcp
```

この手引きは Seriflow 1.1.5 で確かめた。手引きとアプリが食い違うときは
`seriflow_capabilities` の答えを正とする。手引きの入れ方と取り直し方は次の1行。

Claude Code:

```bash
mkdir -p ~/.claude/skills/seriflow && curl -fsSL https://seriflow.app/agent/SKILL.md -o ~/.claude/skills/seriflow/SKILL.md
```

確かめた接続先は Claude Code。それ以外は動くことがあっても対応とは言わない。

## 作業の最初に読むもの

| 読むもの | 呼び方 | 使い道 |
|---|---|---|
| 許可されたモード | `seriflow_capabilities`（引数なし） | `accessMode` と操作名の一覧 `operationNames`。引数の型は `operation` か `operations` で名前を指して読む |
| 作品の版と人の状態 | `seriflow_state` | `version`（作品名 `projectName` を含む）、保存・再生・入力の状態、現在時点、選択 |
| 「ここ」「この字幕」 | `seriflow_get kind=playhead` | 現在時点に見えている字幕・アイテム・立ち絵・背景と、人の選択 |
| 中身 | `seriflow_list` / `seriflow_get` | シーン、セリフ、素材、立ち絵、字幕スタイルなど。ID は必ずここから取る |

`seriflow_list` は1件ごとの中身が大きいので、`limit` と `offset` で少しずつ読む。セリフの一覧は全シーン分が
保存の順に並ぶので、各件の `sceneId` でシーンを、`start` で再生の順を見る。

書き込む操作には毎回 `version` をそのまま `expectedVersion` へ渡し、新しい UUID を `requestID` にする。
結果に入る新しい `version` を次の書き込みに使う。`projectName` が利用者の言う作品と違えば書き込まず確かめる。

## やりたいこと → 使う操作

操作名は `seriflow_edit` の `operation` に渡す編集操作で、`seriflow_` で始まるものはツールと、その動作名や受け先。
手順の詳細と画面のボタン名は右の列のページにあり、利用者へ画面での操作を案内するときもそのページに従う。

| やりたいこと | 使う操作 | 詳しい手順 |
|---|---|---|
| 音声合成ソフトの音声を取り込んでセリフにする | `appendVoiceLines` `insertVoiceLines` `seriflow_begin_upload voiceLines` `seriflow_finish_upload` `seriflow_action importWatchedVoices` | [/help/import-voice-lines](https://seriflow.app/help/import-voice-lines) |
| セリフの順番を入れ替える・別のシーンへ移す | `moveVoiceLine` `moveVoiceLines` | [/help/reorder-lines](https://seriflow.app/help/reorder-lines) |
| 字幕のフォント・大きさ・色を変える | `updateCaptionStyles` `applyCaptionStyle` `setCaptionStyleOverride` | [/help/caption-font-size-color](https://seriflow.app/help/caption-font-size-color) |
| 字幕の改行を変える | `setCaptionLineBreakMode` `setCaptionText` | [/help/caption-line-breaks](https://seriflow.app/help/caption-line-breaks) |
| 立ち絵を追加して画面に出す | `setCharacterVisible` `inheritCharacterSettingsFromPreviousScene` `setLineCharacterArt` `seriflow_begin_upload characterArtFolder` | [/help/character-art](https://seriflow.app/help/character-art) |
| 立ち絵を口パク・まばたきさせる | 外部AIの操作なし（利用者が画面で行う） | [/help/character-lip-sync](https://seriflow.app/help/character-lip-sync) |
| シーンの背景に画像や動画を設定する | `setSceneBackground` `appendSceneBackground` `addSceneWithBackground` `seriflow_begin_upload project` | [/help/scene-background](https://seriflow.app/help/scene-background) |
| 文字や図形を画面に置く（テロップ・吹き出し・矢印） | `addItem` `setItemText` `setItemTiming` | [/help/add-text-item](https://seriflow.app/help/add-text-item) |
| 箇条書きをセリフに合わせて1行ずつ出す | `setItemParagraphStartLines` `assignItemParagraphStartsInLineOrder` `setItemText` | [/help/bullet-list-items](https://seriflow.app/help/bullet-list-items) |
| 画像の背景を切り抜いて人物や物だけを置く | `seriflow_action cutOutBackground` | [/help/cut-out-image-background](https://seriflow.app/help/cut-out-image-background) |
| 文字や画像に登場・退場の演出（フェードなど）を付ける | `setItemEffects` `addItemEffectCue` `setItemMotion` | [/help/item-effects](https://seriflow.app/help/item-effects) |
| BGMや効果音（SE）を入れる | `setAudioRole` `setSceneBGM` `applyBGMToAllScenes` `addSoundEffect` | [/help/bgm-se](https://seriflow.app/help/bgm-se) |
| 別の作品へセリフ・シーン・アイテムをコピーする | `pasteItems` | [/help/copy-between-projects](https://seriflow.app/help/copy-between-projects) |
| 動画をMP4で書き出す・透かしを外す | `setProjectFrameRate` `seriflow_action export` | [/help/export-mp4](https://seriflow.app/help/export-mp4) |

ここに無いやりたいことは `seriflow_capabilities` の操作名から探す。見つからなければ「できない」と答え、
一般的な動画編集ソフトのメニュー名を推測で案内しない。

## 書き込みの決まり

- 編集は `seriflow_edit` に `operations` の配列（各件は `operation` と `arguments`）で最大100件。まとめた分は利用者の ⌘Z で1手に戻る。
- 1件でも存在しない ID を指すと全件が断られる。断られたら一部だけ当たったとは考えない。
- 部分更新の値は次の形で書く。素の値（`42` だけ）は断られる。

```json
{"fontSize": {"set": {"_0": 42}}}
```

- 値を持てる選択肢は、選んだ名前をキーにして値を `_0` に入れる。値を持たない選択肢は空のオブジェクトにする。書き方の詳細は `seriflow_capabilities` の `dataFormats` にある。

```json
{"textColorChoice": {"custom": {"_0": {"red": 1, "green": 0.9, "blue": 0, "alpha": 1}}}, "outlineColorChoice": {"character": {}}}
```

- アイテムをセリフに合わせて出すときは、表示期間をセリフの字幕で指す。秒で置く操作はセリフの並べ替えに追従しない。

```json
{"kind": "captions", "firstCaptionId": "セリフのid", "lastCaptionId": "セリフのid"}
```

- 保存先・開くファイル・書き出し先は人が標準の画面で選ぶ。`userActionRequired` が返ったら利用者に一言頼んで待つ。
- 素材は `seriflow_begin_upload` で宣言し、返る URL へ HTTP PUT で本体を送り、`seriflow_finish_upload` で登録する。任意のパスのファイルを開かせる方法は無い。

## 断られたとき

| 返り値 | 意味 | AI のすること |
|---|---|---|
| `busy` | 人が文字を入力中、ドラッグ中、再生中、確認画面を開いている | 同じ `requestID` で少し待って送り直す。人の入力を止めさせない |
| `conflict` | 読んだ後に人か別の操作が作品を変えた | `seriflow_state` と対象を読み直し、意図がまだ合うか確かめてから新しい `requestID` で送る |
| `wrongProject` | 別の作品の版で書こうとした | 相手の作品を利用者に確かめる |
| `revoked` / HTTP 404 | 作品の切り替えやモード変更で接続が切れた | 同じ URL で `initialize` からやり直し、`seriflow_state` を読み直す |
| `permissionDenied` | モードが足りない | 必要なモード名を利用者に伝える |
| `invalidArguments` | 書き方の誤り | 文面を読み、`seriflow_capabilities` の `operation` で引数の型を読み直して直す |

## 確かめ方

編集の後は `seriflow_render` の `kind` に `image`、`startFrame` に見たいフレームを渡して描く。返る `jobID` を
`seriflow_job` に `inlineImage` を true で渡すと、描いた画像が返る。画像を見てから直し、利用者へ見せる。

## 利用者への報告

始めるときに何をするか一行。終わったら、変えたシーンとセリフを利用者の画面の呼び方（「シーン3のセリフ2」など）で
一、二文と、確認用の画像。ID、操作名、生の JSON は見せない。⌘Z で戻せることは最初の一回だけ伝える。
止まったときは、画面で何が起きているか（入力中、保存先の選択待ちなど）と選べることを平易に書く。

## できないこと

| できないこと | 代わり |
|---|---|
| 共通ライブラリ・立ち絵・表情の削除 | どのモードでもできない。利用者に画面で消してもらう |
| 保存先を決める、任意のパスのファイルを読む | 利用者が標準の画面で選ぶ。素材は AI が `seriflow_begin_upload` で送る |
| 購入・復元・透かしを外す | 利用者が Seriflow の画面で行う |
| 公開中の版に無い機能 | 推測で案内しない。[/help](https://seriflow.app/help) に無ければ無いと答える |
| 台本・セリフ・構成をアプリが考える | Seriflow には無い。AI が考えた案を利用者に見せ、合意してから編集する |