取扱説明書
YouTube自動再生・リアルタイム同期システム「music-auto-play」の機能仕様書・マニュアル
Full Stack Architecture
全ユーザー向け機能
楽曲リクエスト
YouTubeのURLを入力するだけで、簡単に再生キューに追加できます。 ログイン不要で誰でも利用可能です。
メタデータ自動取得
タイトル、再生時間、チャンネル名などを自動で取得してリストに表示します。
重複リクエスト防止
既にリストにある楽曲は追加できません。
「この楽曲はすでに〇番目に登録されています」 と案内されます。
レート制限 (Spam Protection)
短時間の連投を防ぐため、リクエスト追加には回数制限があります。
バリデーション
無効なURLや存在しない動画IDは追加できません。
プレイリストと同期
リアルタイム閲覧
現在の再生曲と、次に再生される曲のリストは 全ユーザーでリアルタイムに同期 されます。プレイヤーの状態（再生中/一時停止）も反映されます。
動画詳細アクセス
リスト内のタイトルをクリックすると、YouTubeの該当ページへ直接アクセス可能です。
リクエスト情報の表示
各楽曲には以下の情報が表示されます：
- 楽曲タイトルとチャンネル名
- 再生時間（動画の長さ）
- リクエストした人（ログインユーザー名またはゲスト）
- リクエスト日時
- キュー内での順番（何番目に再生されるか）
ログインユーザー限定機能
ログイン方法
Google OAuth 2.0
Googleアカウントで安全にログインできます。 メールアドレスが確認済みのアカウントのみが利用可能です。
認証フロー
- 「ログイン」ボタンをクリック
- Googleの認証画面へリダイレクト
- アカウントを選択して許可
- アプリケーションに戻り、セッション確立
自分のリクエスト削除
ログイン中のユーザーは、以下の権限を持ちます。
自己管理権限
自分が追加した楽曲に限り、再生が始まる前であればリストから削除（キャンセル）できます。
※ サーバー側でユーザーID（ハッシュ）を照合し、一致した場合のみ実行されます。
仕様の注意点：ゲストユーザー
ログインせずに（ゲストとして）追加した楽曲は、 たとえ本人であっても後から削除できません。 間違えて追加した場合は、管理者に削除を依頼する必要があります。
管理者機能
管理者認証
管理者専用のユーザー名とパスワードを用いて管理者モードにログインできます。
認証方式
Basic認証により、タイミングセーフな比較でユーザー名・パスワードを照合します。
環境変数（ログイン用）
ADMIN_USER と ADMIN_PASSWORD で設定されます。
パスワード要件
- 最低12文字以上
- 大文字・小文字・数字・特殊文字を各1つ以上含む
セキュリティ
これらの認証情報は秘密鍵と同様に重要です。絶対に公開しないでください。
強制削除権限
あらゆる楽曲を削除可能
管理者は、ユーザーが誰であるか、ログイン状態に関わらず、リスト内の楽曲を強制的に削除できます。
- 不適切な動画の排除
- 再生トラブル時の強制スキップ
- ゲストユーザーが間違えて追加した曲の削除代行
補足: ADMIN_SECRET
管理者削除機能では ADMIN_SECRET 環境変数（32文字以上）も使用されます。
これはログイン認証とは別に、削除操作の権限確認用ハッシュの生成に利用されます。
システム・拡張機能
Chrome拡張機能による制御
自動再生の仕組み
完全自動遷移
- 動画終了を検知して次の動画へ自動遷移
- 前のタブを自動クリーンアップ（閉じる）
- 再生・停止・シーク操作を全ユーザーに同期
- Chromeが起動している間バックグラウンドで動作（サービスワーカーとoffscreenは状況により停止/再開されます）
広告検知・スキップ
- 動画広告を検知し、ステータスに反映
- スキップ可能な広告は自動でスキップを試行
- 広告中は「広告再生中」と表示
- 広告終了後、通常の状態に自動復帰
状態監視
- 再生/停止状態の監視
- シーク（早送り・巻き戻し）の検知
- バッファリング状態の追跡
- タブの開閉を監視
リスト外動画の検知
プレイリストに登録されていない動画が再生された場合、 「リスト外 再生中」 と表示され、紫色のステータスインジケーターで識別できます。
サーバーサイド制御
データの永続化
再生リストはJSONファイル（ローカル）またはMongoDBに保存できます。環境変数で保存先を切り替えられ、 開発環境はJSON、本番運用はMongoDBという使い分けができます。
data/musicRequests.json — ファイルストア（ローカル）PERSISTENCE_PROVIDER=file — デフォルト（JSONに保存）PERSISTENCE_PROVIDER=mongo と MONGODB_URI が必要です（任意: MONGODB_DB_NAME, MONGODB_COLLECTION）。セッション管理
ログイン状態は長期間保持されるCookieセッションで安全に管理されます。最大100年間有効です。
WebSocket通信
Socket.IOによるリアルタイム双方向通信で、クライアント・サーバー・拡張機能の3者が連携します。
レート制限
短時間の連投を防ぐため、IPアドレスごとにリクエスト回数を制限します（デフォルト: 60秒間で10回まで。 RATE_LIMIT_WINDOW_MS / RATE_LIMIT_MAX_ATTEMPTS で変更可能）。
ショートカット
Chrome拡張機能が提供するキーボードショートカット
macOSでは Ctrl の代わりに Command (⌘) を使用します
設定項目 (User Settings)
各ユーザーごとにカスタマイズ可能な設定です。設定はサーバーに保存され、複数のデバイス間で同期されます。
プレイヤーの状態表示形式を変更できます。
再生中の動画ステータスバーを表示するかどうかを切り替えます。
| 設定項目 | 説明 |
|---|---|
ytStatusMode ステータス表示モード | プレイヤーの状態表示形式を変更できます。 compact 簡易表示（デフォルト） player プレイヤー風の詳細表示 |
ytStatusVisible ステータス表示/非表示 | 再生中の動画ステータスバーを表示するかどうかを切り替えます。 true 表示する（デフォルト） false 非表示にする |
保存場所: サーバーサイド（ユーザーIDに紐付けて永続化）
同期: ログイン時に自動的にサーバーから取得され、変更時はリアルタイムで保存されます
ステータスバーの状態表示
ステータスバーは現在のプレイヤーの状態をリアルタイムで表示します。
通常の動画が再生されている状態
動画が停止している状態
YouTube広告が表示されている状態
自動遷移の処理中
リスト外の動画が再生されている
YouTubeタブが存在しない状態（30秒後に自動非表示）
運用上の注意点
ゲストユーザーの削除不可
ログインしていないゲストユーザーが間違ったURLを追加してしまうと、 本人でも削除できません。
この場合、管理者が手動で削除する必要があります。リクエスト前に必ずログインすることを推奨します。
管理者認証情報のセキュリティ
管理者になるための認証情報は、以下の環境変数で設定されます：
ADMIN_USER: 管理者ユーザー名ADMIN_PASSWORD: 管理者パスワード（12文字以上、大文字・小文字・数字・特殊文字を含む）ADMIN_SECRET: 管理者削除権限用のシークレット（32文字以上）
⚠️ これらの情報は秘密鍵と同様に重要です。公開リポジトリにコミットしたり、第三者に共有しないでください。
YouTube API制限
YouTubeの動画情報取得にはYouTube Data API v3を使用しています。 APIには1日あたりのクォータ制限があるため、大量のリクエストを短時間に行うと一時的に情報取得ができなくなる可能性があります。
ブラウザ拡張機能のインストール
自動再生機能を利用するには、Chrome拡張機能のインストールが必須です。
- プロジェクトで
bun run build:extensionを実行 - Chromeの拡張機能管理画面（chrome://extensions/）を開く
- 「デベロッパーモード」を有効化
- 「パッケージ化されていない拡張機能を読み込む」をクリック
youtube-auto-play/distフォルダを選択