
YouTubeの誘惑で時間を溶かさないために、専用の再生アプリをAIと一緒に育ててみた(Webプレイヤー編)
前回の振り返りと今回のゴール
前回(第1回)は、channels.txt に登録した複数チャンネルから、通常動画・ショート・ライブ配信アーカイブの動画本体と詳細メタデータをダウンロードし、差分更新や失敗リトライにも対応した取得スクリプトを作りました。
しかし、保存フォルダから動画ファイルを1本ずつ手動で開いて視聴する形では、YouTubeに比べて不便です。
第2回となる今回は、保存した動画をブラウザ上でYouTube風の黒基調(ダークテーマ)のカードで一覧表示し、クリックして再生できるWebプレイヤー画面を作っていきます。
今回も第1回と同様に、最初から完成形を一気に作ろうとせず、小さなステップで少しずつ組み立てていきます。
まずは保存した動画のサムネイルを一覧表示する
クリックして動画を再生できるようにする(シーク・戻るボタン対応)
詳細メタデータと概要欄を追加する
本日の進め方とフォルダ構成
今回は、前回で作成した動画保存フォルダ(videos/)が存在する作業ディレクトリに、Webサーバーのプログラムを追加していきます。
作業完了時のフォルダ構成は以下のようになりました。
my-youtube-app/
├── channels.txt # 第1回で作成(チャンネル一覧)
├── download.py # 第1回で作成(ダウンロードスクリプト)
├── archive.txt # 第1回で作成(ダウンロード済みID一覧)
├── state.json # 第1回で作成(巡回状態管理)
├── videos/ # 第1回で作成(動画・サムネイル・JSONの保存先)
│ └── チャンネル名/
│ ├── タイトル [動画ID].mp4
│ ├── タイトル [動画ID].webp (または .jpg / .png)
│ └── タイトル [動画ID].info.json
├── app.py # 今回作成(FastAPIサーバー)
└── static/ # 今回作成(フロントエンド画面)
└── index.html # 今回作成(HTML + Tailwind CSS)今回も、AIがローカルのファイル操作やコマンド実行を直接行うエージェント環境(Google Antigravity)で進めています。
ブラウザ版のChatGPTやClaudeなどをお使いの場合は、AIから出力されたコードをそれぞれ app.py、および static/index.html として保存してください。HTMLファイルを直接ダブルクリックしてブラウザで開くのではなく、サーバーを起動した上で http://127.0.0.1:8020 からアクセスします。
事前準備:FastAPI と サーバーツールのインストール
Webサーバーの構築に向けて、FastAPI とサーバー実行ツールの uvicorn をインストールします。
作業ディレクトリ(channels.txt や videos/ があるフォルダ)のターミナルで仮想環境を作成し、有効化します。
macOS / Linux の場合:
python3 -m venv .venv
source .venv/bin/activate
pip install fastapi "uvicorn[standard]"Windows (PowerShell) の場合:
py -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install fastapi "uvicorn[standard]"(※ py コマンドが見つからない場合は python -m venv .venv を実行してください。PowerShellでスクリプト実行ポリシーのエラーが出る場合は、コマンドプロンプトで以下を実行します)
Windows (コマンドプロンプト cmd) の場合:
py -m venv .venv
.venv\Scripts\activate.bat
pip install fastapi "uvicorn[standard]"React等のフロントエンド環境は使わず、HTMLとTailwind CSS(CDN)で完結させるため、Node.jsやnpm等のビルド手順は不要です。
Step 1:保存した動画のサムネイルを一覧表示する
まずは動画再生や複雑な仕組みを作らず、保存された動画のサムネイルとタイトルがブラウザに並ぶ最小限の一覧画面から作っていきます。
1-1. 最小表示プロンプト
AIのチャット画面に以下のプロンプトを入力します。
videos/ フォルダに保存された動画を読み込み、見慣れたYouTubeのように黒基調(ダークテーマ)でカード一覧表示する最小限のWebアプリを作ってください。
出力ファイル:
1. app.py (FastAPIサーバー、インスタンス名は app)
2. static/index.html (画面表示用HTML)
要件:
- Python FastAPI を使用し、静的ファイル配信として static/ フォルダをマウントすること
- フロントエンドは HTML + Tailwind CSS (CDN利用) で完結させ、npm等のビルド環境を不要にすること
- videos/ フォルダ配下のサブフォルダ(チャンネル名フォルダ)を再帰的に走査し、保存されている動画(mp4)とサムネイル画像を収集すること
- YouTube風の黒基調(ダークテーマ)で、各動画のサムネイル画像とタイトルをグリッド状のカードで一覧表示すること
- 他の開発ツールやローカルAIツールとのポート競合を避けるため、待受ポートは 8020 を指定すること
- uvicorn で起動できる完全なコードを出力することAIからは、APIサーバーとなる app.py と、画面表示用の static/index.html が出力されます。
1-2. 動作確認プロンプト
ファイルが配置されたら、サーバーを起動します。(ポート番号の8020は変更可能)
ターミナルで以下のコマンドを実行します。
uvicorn app:app --reload --port 8020エージェント環境をお使いの場合は、AIに以下のプロンプトを入力して動作確認を指示します。
FastAPIサーバーをポート8020で起動して、ブラウザで http://127.0.0.1:8020 にアクセスし、動画一覧が正常にカード表示されるか確認してください。※ブラウザ版AIチャットをお使いの方は、ご自身のブラウザを開き、アドレスバーに http://127.0.0.1:8020 を入力してアクセスしてください。
ブラウザを開くと、黒を基調とした画面に前回保存した動画のカードが並びます。しかし、ここでいくつか表示上の不具合に気づくことがあります。
1-3. つまずきと修正プロンプト(サムネイル欠落・記号対策)
動画一覧を表示した際、以下の2つの現象が発生することがあります。
一部のサムネイル画像が表示されない 第1回の yt-dlp は、動画によってサムネイルを .webp、.jpg、.png のいずれかで保存します。AIが .jpg 決め打ちで画像を探すコードを生成していると、.webp 形式のサムネイルが404エラーになって表示されません。
タイトルに「#」などの記号が含まれていると画像が読み込めない YouTubeの動画タイトルには「#」やスペース、特殊文字が含まれることが多くあります。画像のURLにファイル名をそのまま使っていると、URLの解釈が崩れて画像が読み込めなくなります。
これらの現象を解消するため、以下の修正プロンプトをAIに入力します。
サムネイルの表示について、以下の2点を修正してください。
1. ファイル名から直接画像を探すのではなく、ファイル名末尾の角括弧 [11文字の動画ID] (例: [a-zA-Z0-9_-]{11}) を正規表現で抽出し、動画IDをキーにしたエンドポイント(/thumbnail/{video_id})経由で画像を配信すること
2. サムネイル画像は .webp, .jpg, .png のいずれか存在する拡張子を自動探索して返すこと1-4. 再確認プロンプト
修正が行われたら、サムネイルの表示を確認します。
再度サーバーを動かし、タイトルに記号を含む動画も含め、すべての動画のサムネイル画像が欠落なく正常に表示されるか確認してください。動画のサムネイルが表示され、YouTube風の一覧画面になったかと思います。
Step 2:クリックして動画を再生できるようにする
サムネイルが並んだので、次はカードをクリックしたら画面中央で動画が再生できるプレイヤー機能を組み込みます。
2-1. 動画再生プロンプト
AIに以下のプロンプトを入力し、モーダル再生機能を追加します。
一覧のカードをクリックした際、動画が再生できるように以下の機能を追加してください。
要件:
- カードをクリックすると、画面中央にモーダルウィンドウが開き、背景を暗くして動画を再生すること
- 動画配信エンドポイント(/stream/{video_id})を追加し、ファイル名末尾の動画IDをキーにして動画(mp4)を配信すること
- ブラウザのシークバー操作(HTTP Range リクエスト / Status 206)に標準対応させるため、動画配信には FastAPI の FileResponse(video_path, media_type="video/mp4") を使用することAIから、動画配信処理を追加した app.py と、モーダルプレイヤーを組み込んだ static/index.html が出力されます。
2-2. 動作確認プロンプト
コードを保存したら、動作確認を行います。
サーバーを動かし、カードをクリックした際にモーダルで動画が再生されること、およびシークバーを途中や終盤に動かしても止まることなく再生が継続できるか確認してください。カードをクリックするとモーダルが開き、動画の再生が始まります。動画配信に FileResponse を指定しているため、ブラウザからの HTTP Range リクエストに対してサーバーが Status 206 Partial Content で応答し、シークバーを動かしても止まることなく指定位置から再生されます。
しかし、動画の視聴を終えて一覧に戻ろうとした際に、もうひとつ気になる点が出てきます。
2-3. つまずきと修正プロンプト(ブラウザの「戻る」ボタンと音声停止)
動画を視聴した後、普段のブラウザ操作と同じ感覚でブラウザの「戻る」ボタンを押すと、ローカルサーバーを開く前の画面に戻ってしまいます。
また、モーダルの閉じるボタンを押して画面上は一覧に戻ったように見えても、裏で動画の音声だけが再生され続ける現象が起きることがあります。
この2点を解消するため、以下の修正プロンプトをAIに入力します。
モーダルの操作性について、以下の2点を修正してください。
1. モーダル再生時もブラウザの「戻る」ボタンで一覧画面に戻れるよう、History API (?v=動画ID) と連動させ、ESCキーや背景クリックでも閉じられるようにすること
2. モーダルを閉じた際(戻るボタン、ESCキー、閉じるボタン、背景クリック)には、必ず <video> 要素の再生を一時停止(pause())し、裏で音声が再生され続けないようにすること2-4. 再確認プロンプト
修正が行われたら、戻る操作と音声停止を確認します。
再度サーバーを動かし、動画再生中にブラウザの「戻る」ボタンを押してサムネイル一覧に戻れること、およびモーダルを閉じた際に動画の音声が確実に停止することを確認してください。ブラウザの「戻る」操作でも自然に一覧と動画を行き来できるようになり、プレイヤーとしての基本動作が同じになりました。
Step 3:詳細メタデータと概要欄を追加する
動画が再生できるようになったので、第1回で動画と一緒に保存した詳細メタデータ(.info.json)を活用し、よりYouTubeっぽくしていきます。
3-1. メタデータ・概要欄追加プロンプト
AIに以下のプロンプトを入力します。
保存済みのメタデータ(.info.json)を読み込み、動画情報と概要欄を表示できるようにしてください。
要件:
- メタデータ(.info.json)を読み込む際は、Windows環境での文字化けやエラーを防ぐため必ず encoding="utf-8" を指定すること
- メタデータからチャンネル名、投稿日、再生回数を取得し、カード一覧およびモーダル再生画面に動画情報として表示すること
- 概要欄(description)も取得し、モーダル内の動画下にYouTube風の折りたたみ枠を追加すること
- 概要欄は初期状態で3行程度に制限し、枠内クリックで「もっと見る/一部を表示」を切り替えられるようにすること3-2. 動作確認プロンプト
コードを保存したら、表示を確認します。
サーバーを動かし、カード一覧およびモーダル再生画面にチャンネル名、投稿日、再生回数が表示されていること、そして動画下の概要欄をクリックして折りたたみと展開が切り替わるか確認してください。動画タイトルの下にチャンネル名や投稿日、再生回数が並び、動画下には概要欄が表示されるようになりました。
トラブルシューティング(動画から音が出ない場合)
ブラウザ上で動画が再生され、シークバーも動くものの、音声が一切流れない現象が起きることがあります。
この現象に遭遇した場合は、まず以下の点を確認します。
プレイヤーやブラウザのミュート確認 モーダル内のプレイヤーの音量スライダーがミュートになっていないか、ブラウザタブがミュートされていないかを確認します。
PCの通常プレイヤーでの再生確認 動画ファイル(.mp4)をPC標準のメディアプレイヤーで直接開き、音が出るか確認します。 もしPC標準のプレイヤーでも音が出ない場合は、Webプレイヤーの不具合ではなく、第1回でダウンロードした動画ファイル自体に音声トラックが含まれていません。
ダウンロードスクリプトの点検 第1回のダウンロードスクリプト(download.py)内で、yt-dlp のオプションに -S res,ext:mp4:m4a --merge-output-format mp4 が指定されているか確認してください。 YouTubeの高画質動画では映像と音声が別々に配信されているため、この指定がないと音声を含まない映像専用mp4が保存されてしまうことがあります。 もし特定の動画が無音になっている場合は、download.py のオプションを確認・修正した上で、該当する動画ファイル(.mp4)のみを削除し、再取得を行ってください。
Step 4:完成形の確認
すべての機能が整ったら、全体の動作を確認します。
エージェント環境をお使いの場合は、以下のプロンプトを入力します。
再度サーバーを動かし、すべての動画のサムネイルが正しく表示されること、シークバーを途中や終盤に動かしても止まることなく再生できること、動画再生時に概要欄の折りたたみ・展開ができること、そしてブラウザの「戻る」ボタンを押してサムネイル一覧に戻れ、音声が停止することを確認してください。※ブラウザ版AIチャットをお使いの方は、ご自身のブラウザ(http://127.0.0.1:8020)で上記の動作を順に確認します。
タイトルに記号を含む動画も含めて全件のサムネイルが並び、シークバーのジャンプや概要欄の確認、ブラウザの「戻る」操作でも自然に一覧と動画を行き来できるようになれば、Webプレイヤー画面の完成です。
今回のまとめと次回予告
ローカルサーバーを起動し、広告や関連動画の推薦がない画面で、目的の動画だけを再生できるようになりました。シークバーも追従するため、長時間の動画でも再生したい位置へジャンプして視聴できます。
次回(第3回)は、夜の生活リズムに合わせて「毎日19時に自動で新着を巡回・ダウンロード」する仕組みと、1クリック起動スクリプト(run.sh / run.bat)を作成してアプリを完成させていきます。
最初からすべてのファイルをまとめて揃えたいエージェントユーザー向けに、全機能を統合した一括プロンプトも掲載する予定です。
それではまた次回。