managing-media

メディアとファイルの管理

目的

このスキルでは、あらゆる形式（画像、動画、音声、ドキュメント）に対応するメディアおよびファイル管理コンポーネントを実装するための体系的なパターンを紹介します。アップロードのワークフロー、表示パターン、プレーヤーのコントロール、最適化戦略、アクセシビリティ要件を取り上げ、パフォーマンスに優れ、アクセシブルで使いやすいメディア体験を実現します。

使用するタイミング

以下の場合にこのスキルを有効にしてください。

• ファイルのアップロード（単一、複数、ドラッグ＆ドロップ）を実装するとき
• 画像ギャラリー、カルーセル、ライトボックスを構築するとき
• 動画プレーヤーや音声プレーヤーを作成するとき
• PDF ビューアーやドキュメントビューアーを表示するとき
• メディアのパフォーマンスを最適化するとき（レスポンシブ画像、遅延読み込み）
• 大容量ファイルのアップロード（チャンク分割、再開可能）を処理するとき
• クラウドストレージ（S3、Cloudinary）を統合するとき
• メディアのアクセシビリティ（代替テキスト、キャプション、トランスクリプト）を実装するとき
• メディアがない場合の空の状態を設計するとき

迅速な判断のためのフレームワーク

メディアの種類と要件に基づいて実装方法を選択してください。

Images                  → Gallery pattern + lazy loading + responsive srcset
Videos                  → Player with controls + captions + adaptive streaming
Audio                   → Player with waveform + playlist support
Documents (PDF)         → Viewer with navigation + search + download
File Upload (<10MB)     → Basic drag-drop with preview
File Upload (>10MB)     → Chunked upload with progress + resume
Multiple Files          → Queue management + parallel uploads

詳細な選定基準については、references/implementation-guide.mdを参照してください。

ファイルアップロードのパターン

基本的なアップロード（<10MB）

要件が単純で小さなファイルの場合：

• 視覚的なフィードバックを備えたドラッグ＆ドロップ領域
• クリックして参照するフォールバック
• ファイルの種類とサイズの検証
• 画像のプレビューサムネイル
• 進行状況インジケーター
• references/upload-patterns.mdを参照

例：examples/basic-upload.tsx

高度なアップロード（>10MB）

信頼性が必要な大容量ファイルの場合：

• チャンク分割アップロード（失敗時に再開）
• 複数ファイルの並列アップロード
• アップロードキューの管理
• キャンセルおよび再試行のコントロール
• クライアント側での圧縮
• references/advanced-upload.mdを参照

例：examples/chunked-upload.tsx

画像専用のアップロード

編集要件のある画像ファイルの場合：

• トリミングおよび回転ツール
• アップロード前のクライアント側でのリサイズ
• フォーマット変換（PNG → WebP）
• 代替テキスト入力欄（アクセシビリティ）
• references/image-upload.mdを参照

例：examples/image-upload-crop.tsx

画像表示コンポーネント

画像ギャラリー

画像のコレクション向け：

• グリッドまたはメイソンリーレイアウト
• 遅延読み込み（ネイティブまたはカスタム）
• クリックでライトボックスを表示
• ズームおよびパンのコントロール
• キーボード操作（矢印キー）
• レスポンシブデザイン
• references/gallery-patterns.mdを参照

例：examples/image-gallery.tsx

カルーセル／スライダー

画像を順番に表示する場合：

• 自動再生（任意、アクセシビリティのため一時停止可能）
• ドットまたはサムネイルによるナビゲーション
• タッチ／スワイプ対応
• アクセシビリティのための ARIA ロール
• 無限ループのオプション
• references/carousel-patterns.mdを参照

例：examples/carousel.tsx

画像の最適化

不可欠な最適化戦略：

• srcsetとsizesを使用したレスポンシブ画像
• 最新のフォーマット（JPG にフォールバックする WebP）
• プログレッシブ JPEG
• ぼかしから鮮明になるプレースホルダー
• CDN の統合
• references/image-optimization.mdを参照

動画コンポーネント

動画プレーヤー

カスタムの動画再生向け：

• カスタムコントロールまたはネイティブコントロール
• 再生／一時停止、音量、全画面表示
• キャプション／字幕（VTT 形式）
• 再生速度のコントロール
• ピクチャーインピクチャー対応
• キーボードショートカット
• references/video-player.mdを参照

例：examples/video-player.tsx

動画の最適化

動画のパフォーマンス戦略：

• アダプティブストリーミング（HLS、DASH）
• ホバー時のサムネイルプレビュー
• 画面外の動画の遅延読み込み
• プリロード戦略（metadata、auto、none）
• 複数の画質レベル
• references/video-optimization.mdを参照

音声コンポーネント

音声プレーヤー

音声の再生向け：

• 再生／一時停止、シーク、音量のコントロール
• 波形の視覚化（任意）
• プレイリスト対応
• ダウンロードのオプション
• 再生速度のコントロール
• アクセシビリティのための視覚的なインジケーター
• references/audio-player.mdを参照

例：examples/audio-player.tsx

ドキュメントビューアー

PDF ビューアー

PDF ドキュメントの表示用：

• ページ移動（前へ／次へ、ページ指定）
• ズームイン／ズームアウト操作
• ドキュメント内のテキスト検索
• ダウンロードと印刷のオプション
• サムネイルサイドバー
• references/pdf-viewer.md を参照

例：examples/pdf-viewer.tsx

Office ドキュメントのプレビュー

DOCX、XLSX、PPTX ファイル用：

• 読み取り専用のプレビュー、または編集可能
• クラウドベースのレンダリング（Google Docs Viewer、Office Online）
• ローカルレンダリング（サポートは限定的）
• ダウンロードオプション
• references/office-viewer.md を参照

パフォーマンスの最適化

ファイルサイズのガイドライン

アップロード前にクライアント側で検証します：

• 画像：5MB 未満を推奨
• 動画：ウェブでは 100MB 未満、クラウドではそれ以上
• 音声：10MB 未満
• ドキュメント：25MB 未満
• 明確なエラーメッセージを表示します
• 圧縮ツールを提案します

画像最適化チェックリスト

# Generate optimized image set
python scripts/optimize_images.py --input image.jpg --formats webp,jpg,avif

戦略：

• アップロード前に圧縮します（クライアント側またはサーバー側）
• 複数のサイズ（サムネイル、中サイズ、大サイズ）を生成します
• デバイスに応じて表示するため、レスポンシブな srcset を使用します
• 最新の形式（WebP、AVIF）に変換します
• エッジキャッシュを備えた CDN 経由で配信します

完全なガイドについては、references/performance-optimization.md を参照してください。

動画最適化チェックリスト

戦略：

• 複数の画質（360p、720p、1080p）にトランスコードします
• アダプティブビットレートストリーミングを実装します
• エッジキャッシュを備えた CDN を使用します
• ビューポート外の動画は遅延読み込みします
• ポスター画像を用意します

アクセシビリティ要件

画像

必須のパターン：

• 意味のある画像には代替テキストが必要です
• 装飾画像には空の代替テキスト（alt=""）を使用します
• コンテキストを示すために <figure> と <figcaption> を使用します
• オーバーレイには十分な色のコントラストを確保します
• references/accessibility-images.md を参照

動画

必須のパターン：

• すべての音声にキャプション／字幕を付けます
• トランスクリプトへのリンクを用意します
• キーボード操作（スペース、矢印、ミュートの M）
• 自動再生を一時停止できるようにします（WCAG の要件）
• 音声解説トラック（該当する場合）
• references/accessibility-video.md を参照

音声

必須のパターン：

• トランスクリプトを用意します
• 視覚的なインジケーター（再生中、一時停止中、音量）を表示します
• キーボード操作
• コントロールに ARIA ラベルを設定します
• references/accessibility-audio.md を参照

アクセシビリティを検証するには：

node scripts/validate_media_accessibility.js

完全な要件については、references/accessibility-patterns.md を参照してください。

ライブラリの推奨

画像ギャラリー：react-image-gallery

機能が充実したギャラリーに最適：

• モバイルでのスワイプに対応
• 全画面表示モード
• サムネイルナビゲーション
• 遅延読み込みを標準搭載
• そのままレスポンシブに対応

npm install react-image-gallery

実装例は examples/gallery-react-image.tsx を参照してください。 ドキュメントは /xiaolin/react-image-gallery を参照してください。

代替案： LightGallery（機能がより豊富で、バンドルサイズが大きい）

動画：video.js

カスタム動画プレーヤーに最適：

• プラグインエコシステム
• HLS と DASH に対応
• アクセシブルなコントロール
• テーマ設定に対応
• 充実したドキュメント

npm install video.js

実装例は examples/video-js-player.tsx を参照してください。

音声：wavesurfer.js

波形の視覚化に最適：

• 美しい波形表示
• タイムライン操作
• プラグインに対応
• レスポンシブ
• 軽量

npm install wavesurfer.js

実装例は examples/audio-waveform.tsx を参照してください。

PDF：react-pdf

React での PDF レンダリングに最適：

• ページごとのレンダリング
• テキスト選択に対応
• 注釈（プレミアム）
• パフォーマンスのためにワーカーを使用

npm install react-pdf

実装例は examples/pdf-react.tsx を参照してください。

詳細な比較については、references/library-comparison.md を参照してください。

デザイントークンとの統合

すべてのメディアコンポーネントは、テーマ設定に design-tokens スキルを使用します：

• 背景、オーバーレイ、コントロール用のカラートークン
• パディングと間隔用のスペーシングトークン
• サムネイルとコンテナー用のボーダートークン
• エレベーション用のシャドウトークン
• アニメーション用のモーショントークン

ライト、ダーク、ハイコントラスト、カスタムテーマに対応しています。 テーマの切り替えについては、design-tokens スキルを参照してください。

トークンの使用例：

.upload-zone {
  border: var(--upload-zone-border);
  background: var(--upload-zone-bg);
  padding: var(--upload-zone-padding);
  border-radius: var(--upload-zone-border-radius);
}

.image-gallery {
  gap: var(--gallery-gap);
}

.video-player {
  background: var(--video-player-bg);
  border-radius: var(--video-border-radius);
}

レスポンシブ対応の戦略

画像ギャラリー

レスポンシブ対応のアプローチは 4 つあります。

1. グリッドレイアウト - auto-fit 列を使った CSS Grid
2. メイソンリーレイアウト - 高さが異なる Pinterest スタイル
3. カルーセル - モバイルでは画像を 1 枚、デスクトップでは複数枚表示
4. スタック - モバイルでは縦リスト、デスクトップではグリッド

実装例については、examples/responsive-gallery.tsx を参照してください。

動画プレーヤー

レスポンシブ対応で考慮する点：

• 16:9 のアスペクト比のコンテナー
• モバイルでは全幅表示
• デスクトップでは幅を制限
• マルチタスクに便利なピクチャーインピクチャー
• タッチ操作しやすいコントロール（大きめのタップ領域）

パターンについては、references/responsive-media.md を参照してください。

クラウドストレージとの連携

クライアントサイドからの直接アップロード

AWS S3、Cloudinary などの場合：

1. バックエンドに署名付き URL をリクエストする
2. クラウドストレージに直接アップロードする
3. 完了したことをバックエンドに通知する
4. アップロードしたメディアを表示する

メリット：

• サーバーの負荷を軽減できます
• アップロードが高速になります（CDN に直接アップロード）
• サーバー側のファイルサイズ制限がありません

実装については、examples/s3-direct-upload.tsx を参照してください。 セットアップについては、references/cloud-storage.md を参照してください。

テストツール

モックメディアを生成します：

# Generate test images
python scripts/generate_mock_images.py --count 50 --sizes thumb,medium,large

# Generate test video metadata
python scripts/generate_video_metadata.py --duration 300

メディアのアクセシビリティを検証します：

node scripts/validate_media_accessibility.js

パフォーマンスを分析します：

node scripts/analyze_media_performance.js --files images/*.jpg

動作するサンプル

要件に一致するサンプルから始めます。

basic-upload.tsx              # Simple drag-drop upload
chunked-upload.tsx            # Large file upload with resume
image-upload-crop.tsx         # Image upload with cropping
image-gallery.tsx             # Grid gallery with lightbox
carousel.tsx                  # Image carousel/slider
video-player.tsx              # Custom video player
audio-player.tsx              # Audio player with controls
audio-waveform.tsx            # Audio with waveform visualization
pdf-viewer.tsx                # PDF document viewer
s3-direct-upload.tsx          # Direct upload to S3
responsive-gallery.tsx        # Responsive image gallery patterns

リソース

スクリプト（トークンを消費しない実行）

• scripts/optimize_images.py - 画像の一括最適化
• scripts/generate_mock_images.py - テスト画像の生成
• scripts/validate_media_accessibility.js - アクセシビリティの検証
• scripts/analyze_media_performance.js - パフォーマンス分析

リファレンス（詳細なドキュメント）

• references/upload-patterns.md - ファイルアップロードの実装
• references/gallery-patterns.md - 画像ギャラリーのデザイン
• references/video-player.md - 動画プレーヤーの機能
• references/audio-player.md - オーディオプレーヤーのパターン
• references/pdf-viewer.md - ドキュメントビューアーのセットアップ
• references/accessibility-patterns.md - メディアのアクセシビリティ
• references/performance-optimization.md - 最適化の戦略
• references/cloud-storage.md - クラウド連携ガイド
• references/library-comparison.md - ライブラリの分析

サンプル（実装コード）

• 動作する実装例については、examples/ ディレクトリを参照してください

アセット（テンプレートと設定）

• assets/upload-config.json - アップロードの制約と設定
• assets/media-templates/ - プレースホルダー画像とアイコン

スキル間の連携

このスキルは、他のコンポーネントスキルと連携します。

• フォーム：ファイル入力フィールド、検証、送信
• フィードバック：アップロードの進捗、成功／エラーメッセージ
• AI チャット：画像の添付、ファイル共有
• ダッシュボード：メディアウィジェット、サムネイル
• デザイントークン：すべてのビジュアルスタイルをトークンシステムで適用

次のステップ

1. メディアの種類（画像、動画、音声、ドキュメント）を特定する
2. アップロード要件（サイズ、数量、編集）を決定する
3. 表示パターン（ギャラリー、カルーセル、プレーヤー、ビューアー）を選択する
4. ライブラリを選ぶか、カスタムソリューションを実装する
5. アクセシビリティ要件を実装する
6. 最適化の戦略を適用する
7. パフォーマンスとレスポンシブ動作をテストする
8. クラウドストレージと連携する（任意）