Local Media Helper

Local Media Helperは、Chrome拡張単体では処理できない高画質ビデオ作業をローカルで代行する小さな補助プログラムです。多くのプラットフォームは高画質動画を映像のみのトラックと音声のみのトラックに分離して（DASH）配信しており、ブラウザ拡張だけでは2つのトラックを結合できません。ヘルパーはローカルで両トラックを1つのMP4に結合し、結果をChrome拡張に返します。

デスクトップアプリには同梱されず、独立したRust CLIとして提供されます。メディアのダウンロード自体はChromeがユーザーのブラウザセッションで行い、ヘルパーは結合（mux）のみを担当します。

いつ必要ですか？

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つだけです。

トラブルシューティング

接続確認が失敗する

ヘルパーが実行中であること、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へ直接保存します。

次のステップ

• Chrome拡張
• 動画ダウンロード