🎥動画生成AI用のビデオプレイヤーを Electronで 作ったら、GPUを捨てる羽目になりかかった話

0.はじめに

ローカルに溜め込んだ動画ファイル、どうやって管理していますか？

個人的に、Pinterest風の「Masonryレイアウト」で一覧表示して、スクロールするだけ自動再生されるローカルアプリが欲しいんですよね...。可能であればモバイル対応もしたやつ。

もちろんMasonryレイアウトな投稿サイトを使えば似たようなことはできますが、いちいちアップロードするのも面倒だし、人に見せたくないものもある。ローカルでも管理用のものならなくはないが、ちょっと自分の求めているものとは毛色が違う。

動画アプリ開発やモバイル対応の知識なんてゼロですが、今どきAIがあればなんとかなるっしょということで、いっちょ作ってみました。Electron にもちょっと触ってみたかったことだし。

こんな感じの見た目です。AI感丸出しのダークモードレイアウト。リポジトリは一番下に。

コードのほぼ全てを AI(無課金勢御用達のGoogle AI Studio) を使い倒して生成しています。AIを使ったアプリ開発の事例としても、似たようなものを作りたい方の参考になれば幸いです。
今回は、開発中に遭遇したElectronで動画再生プレイヤーを作るうえの落とし穴について共有できればと思います。何分素人なもんで間違っていることも多いと思います。間違いは指摘していただければ助かります。

1.技術スタックと機能

今の技術スタックは以下の通りです。AIが出してきた初期の構成案に、「Zustand + TanStack QueryとFSD（Feature-Sliced Design）使って」と追加で指示をねじ込みました。
AIにコードを書かせると贅肉が多くて後でリファクタリングに時間を取られることが多いんですが、それを少しでも減らすためにFSDライクなものを採用しています。依存方向の整理も含めて。

• Core: Electron, Vite, React, TypeScript
• Frontend Arch: Feature-Sliced Designライク
• Backend Arch: Service-Repository Pattern
• UI: Tailwind CSS, shadcn/ui, Lucide React
• State: Zustand, TanStack Query
• Database: better-sqlite3 (SQLite)
• Server: Node.js HTTP Server + SSE (Server-Sent Events)

主な機能は以下の通りです。なるべく起動時間が早くなるように設計しています。

• Inode & Partial Hash: ファイルシステム識別子(Inode)と部分ハッシュ計算を組み合わせた、リネームや移動の追跡・自動修復ロジック。
• SQLite FTS5: 動画内の生成プロンプト（JSON）まで対象とした全文検索。
• Metadata Harvester: フォルダを開いた際に全ファイルの解析完了を待たずに一覧を表示。その後バックグラウンドで順次メタデータを取得・反映。
• Custom Streaming Server: Express非依存の軽量実装とSSEによるリアルタイム同期。

2.カスタムプロトコル

今回は、動画プレイヤーの「動画ファイルの読み込み」がメインの話になります。

Electronでローカルファイル（画像や動画）を表示する場合、セキュリティの観点から webSecurity: falseの設定が必要なfile:// プロトコルを直接使うのは非推奨とされています。

なので、定石通りカスタムプロトコルを実装しました。video:// というプロトコルを定義して、それをメインプロセスでフックしてファイルを返す。

// メインプロセス (失敗例)
protocol.handle('video', async (request) => {
  const filePath = request.url.replace('video://', '');
  // ...パスのデコード処理...
  return net.fetch(`file:///${filePath}`);
});

これ、静止画なら全く問題ないんですが、動画プレイヤーとして本格的に使おうとすると、Range Request（部分読み込み） の処理が壁になりました。

行儀の悪いAI生成動画

ブラウザの動画プレイヤーは、動画を効率よく再生するために「ここからここまで（例：0バイト〜1MB）」という部分的なリクエストを投げます。

Electronの net.fetch や protocol.handle でこれを完璧にさばくには、リクエストヘッダーの Range を解析して、レスポンスヘッダーに正しい Content-Range を付けて……という処理を自前で実装する必要があります。

ここが上手くいっていないと、ブラウザ側が「動画のメタデータが正しく読み取れない」「シークなどの挙動が不安定になる」といった問題を引き起こします。さらに致命的だったのが、AI生成動画特有の行儀の悪い動画でサムネイル（初期フレーム）が表示されず、グレーの四角い箱が表示されるだけになる現象でした。この動画については後述します。

再生ボタンを押せば映るんですが、一覧性が著しく低い。「正しく実装すれば動く」とはいえ、動画配信サーバーのロジックをプロトコルハンドラ内で再発明するのは骨が折れます。

3.アプリ内でNode.jsのHTTPサーバーを飼う

「ブラウザ（Chromium）が一番得意なのは何か？」と考えたら、やっぱり普通の HTTP通信 。
変にElectronのプロトコルハンドラで自前実装を頑張るより、アプリ内で localhost のHTTPサーバーを立てて、そこから配信したほうが確実 とAIから提案がありました。

というわけで、メインプロセス起動時に http モジュールでサーバーを立ち上げました。

// electron/lib/local-server.ts (抜粋)
import http from 'http';
import fs from 'fs';

// 実際の実装ではmedia-handler.tsにロジックを分離していますが、概念的にはこんな感じです
const startLocalServer = () => {
  const server = http.createServer((req, res) => {
    // ... (パス取得やセキュリティチェック) ...

    const stat = fs.statSync(filePath);
    const fileSize = stat.size;
    const range = req.headers.range;

    // Range Requestの処理
    if (range) {
      const parts = range.replace(/bytes=/, '').split('-');
      const start = parseInt(parts[0], 10);
      const end = parts[1] ? parseInt(parts[1], 10) : fileSize - 1;
      const chunksize = end - start + 1;
      
      const file = fs.createReadStream(filePath, { start, end });
      
      res.writeHead(206, {
        'Content-Range': `bytes ${start}-${end}/${fileSize}`,
        'Accept-Ranges': 'bytes',
        'Content-Length': chunksize,
        'Content-Type': 'video/mp4', // 実際はmime-types等で判別
      });
      
      file.pipe(res);
    } else {
      // ...通常レスポンス...
      res.writeHead(200, {
        'Content-Length': fileSize,
        'Content-Type': 'video/mp4', 
      });
      fs.createReadStream(filePath).pipe(res);
    }
  });
  
  // ポート0を指定して空いているポートを自動割り当て
  server.listen(0, '127.0.0.1');
};

これで HTTP 経由で動画を配信できるようになり、

• サムネイル表示：グレーだった動画もバッチリ表示

これで解決！...と思いきや、こいつら再生の途中でスタックしまくりやがる。ほんとなんなんだこいつら。

結局、HTTPサーバーを立てても根本的な解決にはなりませんでした。

4.無駄なあがき

VLCプレイヤーでは問題なく再生できるのに、このアプリ（Chromium）でだけ止まってしまう。
VLCプレイヤーの該当動画のログをAIに読ませてみると、どうやらタイムスタンプがずれた動画で起きていました。

問題の動画は、映像データが 0.03秒 地点から始まっていた。

ブラウザの <video> タグは、律儀にデフォルトで 0.0秒 から再生しようとします。しかし、そこにはデータがない（虚無）ため、デコーダーが混乱してスタックしてしまう……という状態のようです（AIが言うには）。

しかたがないので、いろいろ試してみました。

• メモリリークを防ぐために <video loop> 属性を使わず、onEnded イベントで currentTime = 0 に戻して play() する。効果不明。
• 0秒ではなく、0.1秒から再生するようにしてみる。効果なし。デコーダーの部分でスタックしているから描画の部分だけいじっても意味がないか？ただし、負荷分散としてスクロール時のガタつき軽減に効果あり。

「詰んだ？」とGeminiに聞くと、「GPUアクセラレーション切りましょう」 と……マジ？

ということで、GPUを切ってCPUにすることでスタック問題も無事解決しました。
やったね(タイトル回収)！

が、当たり前ですがGPUデコードを無効化したことで、副作用として 動画の読み込みが目に見えて遅くなりました。
スクロールするたびに、動画が表示されるまで数秒間「グレーの四角」が表示されるのは、正直ちょっと体験が悪いです。GPU使いたい...。

しょうがないので、2秒スタックしたら強制再リロードすることで誤魔化すことにしました。

// src/entities/video/model/use-video-playback.ts (抜粋)

// 再生が止まったかの監視ロジック（Watchdog）
useEffect(() => {
  // ネイティブ再生できない形式(ffmpeg変換等)は対象外
  if (!canPlayNative) return;

  let watchdogInterval: NodeJS.Timeout;
  
  // 画面内にいて(inView)、かつ動画をロードすべき状態なのに...
  if (inView && shouldLoadVideo) {
    // 2秒ごとにチェックし続ける
    watchdogInterval = setInterval(() => {
      const vid = videoRef.current;
      
      // readyState < 3 (HAVE_FUTURE_DATA: 再生可能なデータがない) のままスタックしていたら
      if (inView && vid && vid.readyState < 3) {
        console.warn(`[Watchdog] Stuck detected. Retrying... ${video.name}`);
        
        // Stateを更新して強制的にコンポーネントを再レンダリングさせる
        // URLのクエリパラメータに `_v=${viewId}` を付与しているので、
        // これがインクリメントされるとブラウザは「新しい動画だ」と認識してデコーダーをリセットする
        setViewId((prev) => prev + 1);
      }
    }, 2000);
  }
  return () => clearInterval(watchdogInterval);
}, [inView, shouldLoadVideo, viewId, video.name, canPlayNative]);

正直、敗北感はすごいですがこれでよしとしましょう。

可変解像度動画

ここからは推測になるので、話半分に聞いてください。
で、そもそもなんでタイムスタンプがずれてんだって話ですが、タイムスタンプがずれてしまったのは結果であり原因ではないと考えられます。後になってから判明しましたが、問題の動画は途中で解像度が変わる「可変解像度動画」だったんですね。それもGPUが苦手な奇数解像度の。

「GPUが物理的に苦手な処理（奇数解像度）をさせられ、さらに途中でバッファサイズの変更まで要求されて、処理が追いつかずにスタックし、結果としてタイムスタンプがずれた」 ...可能性が高いです。

何これ？

0秒地点の解像度

1秒地点の解像度

このような問題もいずれ無くなるでしょうし、ここの解決に時間を掛けたのは無駄なんだろうなあという気がしないでもない。

5.HTTPサーバーいらん

さて、スタック問題は見切りをつけたので残る最大の問題はパフォーマンス。
詳しくは説明しませんが、以下のような対策をとりました。

• 可視領域に応じたリソース制御（Intersection ObserverによるDOM管理）
• メディアの遅延ロード（高速スクロール中は読み込まず、一定時間表示でロード）
• 無限スクロースの実装（データを小分けにして描画）
• 再レンダリングの抑制（Memo化による最適化）
• バックエンドデータの軽量化（一覧表示に不要な巨大なメタデータを除外して取得）

仮想リストはMasonryレイアウトと相性が悪そうなので挑戦すらしていません。メタデータを事前取得していたら試していたんですが、それをすると起動が遅くなるので...。
このおかげである程度改善が見られましたが、どうしても動画の読み込みが遅い。どこが問題なのかとAIに聞いてみると、ブラウザの同時接続数制限がボトルネックらしい。6個程度に制限されるとか。

ということで6個制限を回避するためにHTTPサーバーを捨て、file:// プロトコルの採用を決定しました。

うん。断然読み込みのパフォーマンス違う。

とはいえfile:// プロトコルを採用するためにはwebSecurity: false(2回目ですが非推奨です)にする必要があり、セキュリティ的な懸念が発生します。モバイル連携も入れたことだし一応以下のような対策を打っておきます。モバイルからのファイル操作も念のため切っておく。穴はあるので使用環境に注意が必要。

・プロセスのサンドボックス化

// electron/main.ts
const mainWindow = new BrowserWindow({
  // ...
  webPreferences: {
    preload: path.join(__dirname, 'preload.js'),
    contextIsolation: true, // UIとプリロードのコンテキストを分離
    nodeIntegration: false, // UI側でのNode.js機能を無効化
    webSecurity: false,     // file:// アクセスのために無効化するが...
  },
});

・ パストラバーサル対策

// electron/lib/server/security.ts
export const isPathAllowed = (targetPath: string): boolean => {
  // アプリで許可されているフォルダ一覧を取得
  const libraryFolders = store.get('libraryFolders') || [];
  const normalizedTarget = path.normalize(targetPath);

  // ターゲットが許可フォルダの「配下」にあるかチェック
  return libraryFolders.some((root) => {
    const normalizedRoot = path.normalize(root);
    return normalizedTarget.startsWith(normalizedRoot);
  });
};

・ CSP (Content Security Policy) による接続制限

<!-- index.html -->
<meta
  http-equiv="Content-Security-Policy"
  content="default-src 'self' ...; img-src 'self' file: blob: data: http://127.0.0.1:*; connect-src 'self' http://127.0.0.1:* ws://localhost:*"
/>

6.HTTPサーバーやっぱいる

で、用済みになったHTTPサーバーですがモバイル配信用にサルベージして使います。

通常のWeb開発であればExpress や Fastify といったWebフレームワークを採用すると専らの噂ですが、Electronアプリでは起動速度への影響が響きそうなので今回は不採用とします。今回の要件は「動画ストリーム」と「SSE」だけなので全てAIに実装させました。

サーバー自体は実装済みなので、次の問題はフロントエンドのPC(IPC通信)と モバイル(HTTP通信)の条件分岐です。全てのコンポーネントに if (isPC) { ... } else { ... } と書くのは面倒なので Factory Pattern を導入し、この分岐を一箇所に封じ込めます。

具体的には、Electronの ipcRenderer.invoke は Promise を返すため、構造的には fetch などのHTTPクライアントと同等に扱えるので TanStack Query を活用し、その queryFn に渡すクライアントを環境に応じて差し替えています。

これ以上は動画プレイヤーとあまり関係がないので割愛します。

7.最後に

個人開発はいろいろ知らないことを勉強できるので楽しいですね。みんなもオレオレ動画プレイヤーを作ろう！
MITライセンス(FFmpegは非同梱)で公開しているのでよかったら使ってみてください。
https://github.com/HoujyouChomei/local-masonry-video-player

P.S.  2回目以降の起動時間(ready-to-show)が322msでちょっとびっくりした。