Local Media Helper

Local Media Helperは、お使いのMac上で動作し、Chrome拡張だけではできない2つの仕事を担う小さな補助プログラムです。

メディアの結合（mux）。 多くのプラットフォームは高画質動画を映像のみのトラックと音声のみのトラックに分離して（DASH）配信しており、ブラウザ拡張だけでは2つのトラックを結合できません。ヘルパーはローカルで両トラックを1つのMP4に結合し、結果をChrome拡張に返します。ダウンロード自体は引き続きChromeがユーザーのブラウザセッションで行い、ヘルパーは結合のみを担当します。

AIチャットのブリッジ。 リーダーモードでは、読んでいる記事についてClaude Codeと対話できます。そのCLIを起動して回答を流し込むのがヘルパーです。記事の内容も、質問も、回答も、すべてお使いのMacの中にとどまります。

デスクトップアプリには同梱されず、独立したRust CLIとして提供されます。

いつ必要ですか？

リーダーモードのAIチャット（必須）

• リーダーモードのAIチャットは、ヘルパーがインストール・ペアリングされている場合にのみ開きます。
• Claude Code CLIのインストールとログインも必要です — AI CLIセットアップを参照してください。
• 現時点ではmacOS専用です。

TikTokクリップ（必須になる場合あり）

• 多くのTikTok動画は音声/映像が分離したストリームで配信されます。これらをClip to Obsidianで保存するにはヘルパーが必須です。ヘルパーがない場合、ポップアップは「This TikTok video needs the Local Media Helper」というメッセージとともにクリップを中断します。
• progressive（単一ファイル）の動画はヘルパーなしでもクリップできます。

Facebookリールのクリップ（任意）

• 音声/映像が分離したFacebookリールは、ヘルパーがあれば音声付きの1つのMP4として保存されます。ない場合もクリップ自体は完了しますが、映像のみ（無音）のファイルになります。

Instagram → Immich高画質アップロード（任意）

• Instagramのsaved posts、my posts、プロフィールグリッドをImmichへアップロードする際に動画品質を最大限保ちたいとき
• Instagramが高画質動画をvideo-only/audio-onlyのsidecarでのみ提供し、低画質のprogressive動画だけをfallbackとして返すとき
• ImmichサーバーがRaspberry Piのような軽量機器で、Social Archiver専用の処理ツールを載せたくないとき

ヘルパーがなくてもImmichアップロードは動作し続けます（低画質fallback）。

インストール

macOSでは、Local Media Helperの.pkgインストーラーをダウンロードしてダブルクリックでインストールします。インストールが完了すると、ヘルパーアプリ、ログイン時の起動項目、Chromeペアリングサポートが一緒に登録されます。

インストール後、Chrome拡張のOptionsでPair Local Helperをクリックします。通常のインストールフローでは手動でのトークンコピーは不要です。

ヘルパーアプリを直接開いてもインストールは実行されず、現在の実行状態と次のステップが表示されます。

開発実行

ソースから直接実行:

cd local-media-helper
cargo run -- serve --token local-test-token

デフォルトアドレス:

http://127.0.0.1:8787

ローカルにインストール:

cd local-media-helper
cargo install --path .
social-archiver-local-media-helper serve --token local-test-token

--tokenを省略すると、ヘルパーは一時的なペアリングトークンを生成してターミナルに出力します。開発実行ではffmpegが必要になる場合があります。

macOS:

brew install ffmpeg

Debian/Ubuntu:

sudo apt install ffmpeg

Windowsではscoop install ffmpegまたは公式のffmpegビルドが使えます。

Chrome拡張の設定

Chrome拡張のオプションで次の値を設定します:

Local Media Helper URL: http://127.0.0.1:8787
Pairing Token: Pair Local Helperボタンで自動設定
Use local helper: on
Prefer helper for high-quality Immich videos: on

保存時にChromeがhttp://127.0.0.1:8787/*の権限を求めることがあります。拡張機能がヘルパーに/healthと/media/dash-muxリクエストを送れるよう、許可してください。

ローカルパッケージの作成

開発者がテスト用バイナリを作る場合:

cd local-media-helper
./scripts/package-local.sh

成果物はlocal-media-helper/dist/以下に作成されます。MVP段階ではsigned/notarizedされたアプリパッケージではないため、配布前にOSごとのセキュリティ警告とインストールフローを別途検証する必要があります。

セキュリティ境界

• ヘルパーはデフォルトで127.0.0.1のみにバインドします。
• /media/dash-muxはbearerトークンがないと呼び出せません。
• ヘルパーはInstagramのCookie、ImmichのAPIキー、Social Archiverのトークンを受け取りません。
• ヘルパーは任意のシェルコマンドを実行せず、決められたffmpegのmuxコマンドのみを使用します。
• 一度に処理するmuxジョブは1つだけです。

AIチャットの場合:

• /ai/*も/media/dash-muxと同じbearerトークンがなければ呼び出せません。
• 記事の内容は信頼できないWebコンテンツのため、ヘルパーはClaude Codeのツールをすべて無効にした状態で起動します — 回答はできますが、ファイルの読み取りやコマンドの実行はできません。空の作業ディレクトリで実行されるため、プロジェクト設定やCLAUDE.mdも読み込まれません。
• 応答が止まった場合は所定の時間で終了し、同時に実行できるチャットは最大2件です。
• 会話がSocial Archiverのサーバーへ送られることはありません。ユーザー自身のClaude Codeプランを使い、ローカルのClaude Codeセッション履歴に保存されます。

トラブルシューティング

接続確認が失敗する

ヘルパーが実行中であること、URLとトークンが拡張機能の設定と一致していることを確認してください。別のポートで起動した場合は、拡張機能設定のURLも合わせて変更してください。

ffmpegが見つからない

ffmpegがPATHにない場合は、実行時にパスを直接渡します:

social-archiver-local-media-helper serve --token local-test-token --ffmpeg /path/to/ffmpeg

動画がfallbackでアップロードされる

想定どおりの動作の可能性があります。ヘルパーが失敗した場合や、progressive動画で十分と判断された場合、Chrome拡張は既存のbrowser-ready動画をImmichにアップロードします。

TikTokクリップがヘルパーを要求する

そのTikTok動画が音声/映像分離ストリームで配信されているためです。ヘルパーをインストールし、拡張機能の設定で有効化してから再度クリップしてください。拡張機能の設定でVaultフォルダも選択されている必要があります — TikTokクリップは結合済みの動画ファイルをVaultへ直接保存します。

AIチャットがClaude Codeのログインを求める

CLIが認証できない場合、チャットパネルにSign in to Claude Codeカードが表示されます。Claude Codeの更新で保存済みのログイン情報が消えることがあり、その後も対話型CLIはログイン済みに見えることがあります。実際にリクエストを送るコマンドで確認してください:

claude -p "say OK"

認証エラーが出た場合は、ターミナルでclaudeを実行し/loginでサインインしてから、メッセージを送り直してください。カードの再確認ボタンはログイン状態を検証できず、入力欄を再度開くだけなので、送り直すことが本当の確認になります。

次のステップ

• リーダーモード
• AI CLIセットアップ
• Chrome拡張
• 動画ダウンロード