# Videog Player 4.0 — 機械可読仕様 (llms.txt)

> このファイルは https://console.videog.ai/lp/player/docs/ の機械可読版です。
> AI・MCPクライアント・自動レビュー向けに、Videog Player 4.0.0 の利用契約
> (パラメータ・型・後方互換) を1ファイルで記述します。
> 人間向けページ: https://console.videog.ai/lp/player/docs/
> 最終更新: 2026-08-16 / 対象バージョン: videogplayer 4.0.0

## 概要

- Videog Player は video.js ベースの動画プレーヤー。UMD バンドル 1 本 + CSS 1 本で動作する。
- 動作に必要な情報 (動画ソース・字幕・資料・共有/ダウンロード先) は **すべて初期化オプションで注入**する。
  **プレーヤー本体 (UMD バンドル)** は fetch / XHR / ハードコード URL を持たない (完全パラメータ駆動)。
  ※ 埋め込み側のページ (console.videog.ai の視聴ページ等) が options を API から取得して渡すのは別レイヤー。
- **後方互換の保証**: 3.0 系で使えた全オプションは 4.0.0 でも**名前・型・既定値 (スキーマ) とも同一に受理・動作**する。
  4.0 の新オプションはすべて追加式 (指定しなければ 3.0 挙動)。UI の見た目・内部実装は
  バージョンで進化する (下記「4.0.0 での挙動変更」参照)。
- 配信元 (CDN): `https://cf-rsc01.videog.jp/r/js/videog_player/<version>/videogplayer.{js,css}`
  - 本番は `/<version>/` (バージョン固定) を推奨。`/current/` (最新安定) は追随運用向け

## 読み込みと初期化

```html
<link rel="stylesheet" href="https://cf-rsc01.videog.jp/r/js/videog_player/4.0.0/videogplayer.css">
<script src="https://cf-rsc01.videog.jp/r/js/videog_player/4.0.0/videogplayer.js"></script>
<div id="player"></div>
<script>
  videogplayer({ id: 'player', play_list: [{ file: 'https://…/master.m3u8' }] });
</script>
```

- グローバル `videogplayer(options)` はファクトリ関数。`id` で対象 DOM 要素を指定する。

## iframe 埋め込み (KINTOKI / console.videog.ai)

```html
<iframe src="https://console.videog.ai/player/{hash}/"
  width="640" height="360" frameborder="0"
  allow="autoplay; fullscreen; picture-in-picture; encrypted-media"
  allowfullscreen></iframe>
```

- 埋め込みコードはプレーヤーの共有パネル (共有ボタン → 埋め込みコード) から取得できる。
- 動画側の視聴制限 (ID/パスワード・ドメイン・IP・視聴期限・シーク禁止・プロテクト) は埋め込み先でも適用される。

## 視聴ページの URL パラメータ

| パラメータ | 例 | 意味 |
|---|---|---|
| `t` | `?t=95` / `?t=1m35s` | 再生開始位置 (秒 または h/m/s 表記。YouTube 互換) |
| `start` | `?start=95` | 同上。`t` と併記時は `start` が優先 |

## 初期化オプション (4.0.0 で追加)

| オプション | 型 | 既定 | 説明 |
|---|---|---|---|
| `btn_chapters` | `[{start:number, title:string}]` | なし | 目次 (チャプター)。メニュー表示は「m:ss タイトル」形式・クリック開閉ロック式。章バーも表示 |
| `double_tap_seek` | boolean | `true` | スマホの左右ダブルタップ 10 秒戻し/送り。長押しで倍速加速 |
| `btn_seek_disable` | `{message?:string}` | なし | シークバー操作と前進操作を禁止。操作時に message を表示 |
| `play_list[].captions` | `{list: [{url, label, language?, default?}]}` | なし | sidecar VTT 字幕 (プレイリスト項目単位)。`default:true` のトラックを初期表示。内部的には 3.0 の `textTracks` に変換される (= `textTracks` 直指定も従来どおり有効。両方指定時は `captions` 優先) |
| `seek_sprite` | `{url, tile, slides?, duration?}` | なし | シークバーホバーのサムネイルプレビュー (スプライトシート方式)。`btn_chapters` 指定時もプレビュー面が有効になる |
| `elearning` | `{slides, cues, chapters, layout}` | なし | Eラーニング資料レイヤー。データは丸ごと渡す (プレーヤーは取得しに行かない) |
| `play_list[].slides` | `[{start:number, image:string}]` | なし | スライドキャスト (MP3 音声 + 画像の時刻同期再生) |
| `long_press_speed` | boolean | `true` | スマホの画面長押しで一時的に倍速 (離すと戻る)。false で無効化 |
| `btn_share.sites` の `'line'` | string (語彙追加) | — | 共有先語彙に `'line'` を追加 (LINE で共有)。`btn_share` 自体の形は 3.0 と同一 |
| `skin` | string | `'light_blue'` | 4.0 で `skeleton_vidstack` (スケルトンブラック) / `skeleton_white` を追加。従来 8 スキン (light_blue/light_white/light_black/light_red/light_green/hard_blue/hard_red/hard_white) も継続 |

補足: ピクチャーインピクチャー (PiP) ボタンは対応ブラウザで、画質選択ボタンは
マルチビットレート HLS のときに、それぞれ自動で表示される (専用オプション不要)。

## 初期化オプション (3.0 から継続 — 契約不変)

| オプション | 型 | 説明 |
|---|---|---|
| `id` | string | マウント先要素 id |
| `play_list` | array | 再生リスト。`[{file, title, poster, textTracks, logo, …}]` (`slides` / `captions` は 4.0 追加) |
| `autostart` / `mute` / `repeat` | boolean | 自動再生 / ミュート開始 / リピート |
| `player_width` / `player_height` | number\|string | プレーヤー寸法 |
| `title` | boolean\|string | タイトル表示 |
| `background_color` / `active_color` | string(color) | 背景色 / アクセント色 (skin 未指定時) |
| `right_click` | boolean | 右クリックメニュー抑止 |
| `logo` | object | ロゴ表示 `{file, link, position, margin, hide}` |
| `btn_play` / `btn_seek` / `btn_fullscreen` / `btn_volume` | boolean | 各コントロールの表示 (既定 true) |
| `btn_10s_forward` / `btn_10s_backward` | boolean | 10 秒送り / 戻しボタン |
| `btn_pre` / `btn_next` | boolean | プレイリスト前後ボタン |
| `btn_videolist` | boolean\|object | 再生リストパネル |
| `btn_share` | `{heading?:string, link?:string, code?:string, sites?:string[]}` | 共有パネル。`link` 省略時は現在 URL。`code` を渡すと埋め込みコード欄を表示。`sites` は `'line'`(4.0 追加) / `'facebook'` / `'twitter'` / `'email'` |
| `btn_video_download` | string(URL) | 動画ダウンロードボタン。値の URL へ遷移するだけ (URL の中身は埋め込み側の自由) |
| `btn_document_download` | `{url:string, text?:string}` | 資料ダウンロードボタン。`text` 省略時は「ドキュメントダウンロード」 |
| `completed_jump` | object | 視聴完了時のジャンプ |
| `ga` | object | Google Analytics 連携 |
| `audio_mode` | boolean | 音声のみモード |
| `rotate_angle` | number | 映像回転 |

注記:
- `btn_subtitles` / `error_504` / `player_mode` / `player_type` は 3.x 時点からバンドル側では未使用
  (ドキュメント側の項目)。4.0 でも挙動差なし。
- 全オプションの 3.0 版詳細: https://player.videog.jp/docs/

## 4.0.0 での挙動変更 (意図的・2 点のみ)

1. **ボタンラベルはテキスト描画**: `btn_document_download.text` など利用者入力ラベルは
   textContent で描画され、HTML は解釈されない (格納型 XSS 対策。契約上ラベルは元々テキスト)。
2. **共有パネルの刷新**: パネルの見た目・構成は現代化 (リンクコピー・開始位置チェック・SNS・埋め込みコード)。
   オプション契約 (`btn_share` の形) は 3.0 と同一。

## KINTOKI (console.videog.ai) 連携仕様

プレーヤーページはバックエンド API から options を受け取って初期化する。埋め込み側が意識する必要はないが、
セカンドオピニオン・監査用に配信面の契約を記す。

- `GET /api/v3/player/media/{hash}/info` → `data.options` にプレーヤーオプション一式
  (`btn_share` / `btn_video_download` / `btn_document_download` は動画設定に連動して出し分け)。
- **動画/音声ダウンロードは期限付き署名 URL** (2026-08-16〜):
  - ダウンロード URL は API が発行する。署名なし・期限切れ・改竄・別ファイルへの流用はすべて拒否され、
    URL を自前で組み立てることはできない (プレーヤー / コンソール経由限定)。
- 字幕: `GET /api/v3/player/media/{hash}/captions` → `data[]` = `{id, label, language, url, default}`。
  `default` は動画設定「字幕のデフォルト表示」が ON のとき先頭トラックのみ true。
- 資料 DL: `GET /api/v3/player/media/{hash}/elearning/documents/download`
  — その動画に紐づけられた資料のみ (他の動画の資料は取得できない)。
- Eラーニング資料フィード: `GET /api/v3/player/media/{hash}/slides`
  → `{hasSlides, layout, slides, cues, chapters, duration}` をページ側が取得しプレーヤーへ注入。
  `cues[].layout` は www elearning_timeline.index_slide_place 互換 (0-4)。

## Eラーニング配置 (7 パターン)

視聴者は配置メニューで切替可能。内部値は www placelist 互換。

| No | 名称 | 内部値 |
|---|---|---|
| 1 | 資料大 + 動画上 | 0 |
| 2 | 資料大 + 目次 | 1 |
| 3 | 動画大 + 資料上 | 2 |
| 4 | 動画大 + 目次 | 3 |
| 5 | 目次大 + 動画下 | 4 |
| 6 | 動画のみ | 6 |
| 7 | 音声 + 資料 | 5 |

- 768px 未満 (compact) では横並び配置は縦積みへ自動写像。

## 参照

- 人間向けガイド: https://console.videog.ai/lp/player/docs/
- フルリファレンス: https://player.videog.jp/docs/
- プレーヤー JS API (関数・イベント): https://player.videog.jp/api/