コンテンツ制作 · nateherkai/hyperframes-student-kit

cut-mistakes

動画編集パイプラインの Agent 2。トーキングヘッド(語り)動画から、言い淀み(吃音)、単語の重複、言い直し(ファルスクスタート)、リテイク(再録テイク)などの発話ミスを検出・削除します。cut-silences の実行後、ミス箇所のカット、吃音・重複・つなぎ言葉のやり直しの削除、言い損じのクリーンアップ、またはベストテイクの選定を行う際に使用します。レビューゲート方式で動作し、文脈と承認理由を添えてすべてのカット候補を提案した上で、ffmpeg 経由で承認されたカットのみをレンダリングします。単語レベルの文字起こし(ワードレベルトランスクリプト)が必要です。

L4 高権限 · 段階的認可と監査V1 コミット固定コマンド実行ネットワーク通信ファイル書き込みDual-pass Audit
Author nateherkaiGitHub nateherkai/hyperframes-student-kit ↗Stars 1070License NOASSERTION(仓库根 LICENSE,实为 MIT 文本)Commit 0d30152a82
管理レベルは Skill の能力と推奨統制措置を示すものであり、品質や安全性の認証、利用可否の判定ではありません。使用の可否はユーザーおよび管理者が決定します。Agent 環境によって制約が異なるため、自動保護を仮定しないでください。第三者製 Skill の著作権は原著作者に帰属し、利用リスクは利用者が負います。

1仕組みと動作原理

「言い間違い」の処理を3ステップのパイプラインに分割:機械的な候補検出 → 必須のレビューゲート → 承認されたカット点のみレンダリング。判断はLLM/人間に、計算はスクリプトに委ねます。

.claude/skills/cut-mistakes/SKILL.md
### 1. Find candidates (mechanical) … ### 2. Review (the gate — REQUIRED) … ### 3. Apply approved cuts
SKILL.md の中核設計:検出スクリプトは候補 + 信頼度 + デフォルト推奨のみを出力し、承認リストがレンダリングへの唯一の入力となります。

吃音(stutter)の判定=隣接する2つの単語トークンが同一かつ間隔が0.5秒未満。デフォルトでは前者を削除し後者を残します。

.claude/skills/cut-mistakes/scripts/find-cut-candidates.mjs
const closeGap = b.start - a.end < 0.5; if (a.token === b.token && closeGap) { … // remove the first utterance, keep the second cut: { start: Number(a.start.toFixed(3)), end: Number(b.start.toFixed(3)) },
トークンは cleanToken() で前後の非英数字を事前に除去するため、"the." と "the" は同一トークンと判定されます。候補には判断用に removes/keeps/context が付与されます。

リテイクや言い直しの検出は静的なルール列挙に依存せず、ポーズ/文末/16秒の上限でチャンク分割した上で、ストップワード除外後のシグネチャを Jaccard 類似度で比較します。

.claude/skills/cut-mistakes/scripts/find-cut-candidates.mjs
if (gap > 0.85 || (sentenceEnd && elapsed >= 7.5) || elapsed >= 16) { … const stop = new Set("a an and are as at be but by for from i if in is it of on or so that this to was we with you your they their there what when where why how like um uh".split(" ")); … const score = jaccard(sigs[i], sigs[j]); const sameOpening = sigs[i].slice(0, 4).filter((t, idx) => t === sigs[j][idx]).length >= 2; if (score >= 0.34 || (score >= 0.24 && sameOpening)) {
類似度しきい値は二重基準:score ≥ 0.34 で重複判定、≥ 0.24 かつ冒頭4単語中2単語が一致する場合も該当。比較ウィンドウは後続8チャンクかつ間隔 ≤ 75秒に制限されます。

「短い先頭チャンク + 素早い再開」を言い直し(ファルスクスタート)と判定し、種別を retake から false_start へ変更します。

.claude/skills/cut-mistakes/scripts/find-cut-candidates.mjs
const isFalseStart = sameOpening && firstLen < 6 && segments[j].start - segments[i].end < 12; … type: isFalseStart ? "false_start" : "retake",
種別の変更はラベルと説明テキストにのみ影響し、カット範囲自体は同じ類似度ロジックから算出されます(デフォルトは先行するテイクを削除し、より明瞭な再開テイクを残します)。

検出器は「決定を行わない」ことを明示しており、強調のための重複と言い間違いが機械的に同形となるため、SKILL.md は文脈を1件ずつ確認することを義務付けています。

.claude/skills/cut-mistakes/scripts/find-cut-candidates.mjs
This is MECHANICAL detection only. It proposes candidate cut ranges with rich … context + a confidence + a default recommendation, but it does NOT decide.
SKILL.md にはさらにこう記載されています:"The mechanical detector cannot tell intentional emphasis/rhetoric from a real flub, so do not trust `recommend` blindly — read `removes` + `context`."

承認リストは apply-cuts.mjs を通じて EDL + リタイム済み文字起こしに変換されます。--apply 指定時のみ ffmpeg trim/atrim + concat でレンダリングし、デフォルトはドライランです。

.claude/skills/cut-mistakes/scripts/apply-cuts.mjs
if (approved.some(c => c.start < 0 || c.end > duration)) die('Cut range is outside source duration bounds'); … lines.push(`[0:v]trim=start=${r.start.toFixed(3)}:end=${r.end.toFixed(3)},setpts=PTS-STARTPTS[v${i}];`); … const ff = spawnSync("ffmpeg", ["-y", "-i", videoPath, "-/filter_complex", scriptPath, "-map", "[v]", "-map", "[a]", "-c:v", "libx264", "-preset", "medium", "-crf", "18", "-c:a", "aac", "-b:a", "192k", "-movflags", "+faststart", outputPath], { stdio: ["ignore", "ignore", "inherit"] });
スクリプト内で境界値検証を実施(範囲外は即時停止)。フィルタ定義を *.mistakes-filter.txt に書き出してから -/filter_complex に渡し、--apply がない場合は "re-run with --apply to render" の案内のみを出力します。

2コア機能

01言い間違い候補の検出:吃音 / リテイク / 言い直しの3種別、それぞれ信頼度とデフォルト推奨付き
02構造化された候補データ + 人間可読な提案書のデュアル出力(エージェント用JSON、人間確認用MD)
03レビューゲート:recommend を鵜呑みにせず、文脈を1件ずつ確認して決定
04承認リスト → EDL + リタイム済み文字起こし(元動画との照合用に source_start/source_end を保持)
05レンダリング / ドライランのデュアルモード:デフォルトはEDLと文字起こしのみ出力、--apply 指定時のみ ffmpeg を実行
06リポジトリレベルのレビューツールを活用した、ブラウザで確認可能な EDL レビューページの生成
07「カット点ゼロ」を正当な結果として許容し、エージェントに不要なカットノルマを課さない

3外部依存関係

KindDependency / Endpoint
cliNode.js(跑两个 mjs 脚本)
cliffmpeg(trim/atrim + concat 渲染,libx264/aac)
cliffprobe(转录未带时长时探源片时长)
clinpx serve(只服务本地审查页 HTML,非上传)
clinode scripts/build-edl-review.mjs(仓库级共享复核工具,不在本 skill 目录内)

4推奨統制措置と判定根拠

安全運用のための推奨統制措置
Agent 向け
段階的・都度認可、サンドボックス推奨
管理者向け
承認フロー、ロールバック可能、全履歴監査
判定根拠(ファイルパスと抜粋)
  • scripts/: ローカルスクリプトまたはコマンドの実行: node .claude/skills/cut-mistakes/scripts/find-cut-candidates.mjs <transcrip
  • 网络端点: 外部ネットワークアクセスの宣言: 唯一の HTTP 面は人間による確認フェーズの `npx serve . -p 8080 -n` のみ(ローカル静的サーバーで、生成済みレビューHTMLを配信するだけでメディアのアップロードは行いません)
  • 本地工作目录: ファイル読み書きおよび成果物出力: <stem>.cut-candidates.json / <stem>.cut-candidates.md(デフォルトでは文字起こしと同じディレクトリ、または --out-dir に出力)
監査ノート: 判定対象は本スキル自体のディレクトリ(SKILL.md + 2本のスクリプト、計3ファイル)です。2本の .mjs はすべてローカルの Node ロジックであり、文字起こし JSON を読み込んで候補/EDL/文字起こし/マークダウンを出力します。唯一の子プロセス呼び出しは ffprobe および ffmpeg の固定バイナリのみで、ネットワーク通信、認証情報読み取り、環境変数アクセスのいずれも0件であり、削除や破壊的な操作もありません。したがって、青色の「ローカルスクリプト/CLI およびローカル読み書きのみ」に分類されます。なお、隣接する外部要素(本スキルのディレクトリ外のため判定区分には影響しません):前工程の文字起こしはリポジトリ共通の `scripts/transcribe-elevenlabs.mjs` で行われ、ELEVENLABS_API_KEY を読み出して音声を api.elevenlabs.io にアップロードします(素材の外部送信とクォータ消費が発生)。ただし、これは本スキルが明示的に責務外としている上流工程です(本スキルは任意の単語レベル文字起こしを受け入れ、キー不要なローカル Whisper 出力の正規化データも利用可能)。また、SKILL.md が指示する確認ページの生成(scripts/build-edl-review.mjs)もローカルスクリプトです。

5二重目の独立検証

  • [ok] 目录文件清单与产物对照 — 3 个文件(SKILL.md、find-cut-candidates.mjs、apply-cuts.mjs);SKILL.md 承诺的 *.cut-candidates.json/.md 与 *.mistakes-edl.json/transcript.json/decisions.md/filter.txt 均在两个脚本的 writeFileSync 目标中逐一定位到。
  • [ok] 网络面反例搜索 — 目录内 0 处 fetch/https 导入;唯一 URL 形态字样是 SKILL.md 的本地命令 `npx serve . -p 8080 -n` 与仓库级脚本名,不构成执行期外发。
  • [ok] 凭证面反例搜索 — 0 处 process.env/API_KEY/TOKEN/.env;spawnSync 列表仅 ffprobe/ffmpeg,环境变量未被子进程继承修改。
  • [ok] 「只渲染已批准切点」是否被代码强制 — apply-cuts.mjs 第 49-51 行以 --cuts 文件为唯一输入并校验数组与非空范围;find-cut-candidates.mjs 不含任何写视频/批准逻辑,两脚本互不自动串接。
  • [ok] 文档参数 vs 脚本 argv — find 脚本解析 <transcript> 与 --out-dir(Usage 行自述一致);SKILL.md 给的命令两种形态都能对上。apply-cuts 解析 --cuts/--video/--output/--out-dir/--apply,与 SKILL.md 的调用示例逐项一致。
  • [ok] 上游转录服务是否被算作本 skill 行为 — SKILL.md 只写「Requires a word-level transcript」,未指名任何服务或 key;ElevenLabs helper 属仓库级 scripts/,故按『判级对象=skill 自身目录』记入 reason/risks 而不改档。

6結論

  • 「意味的判断」と「数値計算」を完全に分離し、正規表現で人間の発話を理解したつもりになる典型的な失敗を防止:スクリプトは候補+信頼度+推奨のみを提示し、SKILL.md は removes/context の精読を厳格に要求します。
  • リテイク/言い直しにはハードコードされたフレーズではなくチャンク分割 + Jaccard の二重しきい値(0.34 / 0.24 + 冒頭一致)を採用し、テイクが乱立する生素材に対しても高い頑健性を誇ります。
  • デフォルトのドライラン、ファイル書き出し前のカット境界検証、decisions.md および確認用プレビューページの出力により、編集判断の追跡とロールバックが容易です。
  • 前工程で無音カットされたタイムラインを引き継ぐため、リタイム済み文字起こしが後工程の beat-sync 検証と自然に整合し、パイプライン結合の摩擦を抑えられます。
  • 誤検出や検出ゼロに対する明確な方針(3つの典型的な偽陽性パターンの提示、クリーンな素材での0カット許容)により、過剰編集への衝動を抑制します。
  • 最適な用途: 最適:単語レベルの文字起こしが存在するトーキングヘッド長尺動画の2巡目粗編集/本編集(YouTubeトーク動画、チュートリアル、インタビューのセルフ編集)、および編集プロセスに追跡可能性を求めるチームワークフロー。「スクリプトで計算し、モデルで判断する」権限分離の設計パターンを学びたい方にも適しています。
    不向きな用途: 非推奨:文構造の再構成や意味レベルの言い換えが必要な編集(単語順の変更は行わず時間区間の削除のみ)、単語レベルのタイムスタンプがない文字起こし(SRTや段落単位は非対応)、マルチカメラ/話者切り替え、および人間によるレビューなしの完全自動バッチ処理(レビューゲートが設計上の必須要件です)。
    Install Agent-Ready
    ① Verified Mirror 2026-09-28
    Option A · Direct DownloadDownload cut-mistakes.tar.gz
    sha256: fca023adfb7af7d9…
    Option B · Copy Guide for Agent
    install.json
    Agent はこの JSON ガイドから自動的にダウンロードして検証します。
    ② Upstream GitHub
    GitHub Repo ↗
    Pinned to commit 0d30152a82.