KANADE — 要件定義書 兼 Claude Code 実装指示書

版数 1.0（DBレス構成 / 記事埋め込み型デモ）／ 作成日 2026-08-17 ／ 発行 ソウゾウ合同会社 用途 SEO記事「【デモで試せる】Claude Codeで音楽アプリを開発する方法と費用｜動画つき資料【2026年】」に組み込む実演デモ

このドキュメントの使い方（Claude Code へ）

これ1枚が、規約・仕様・タスクのすべて。リポジトリ直下に CLAUDE.md として置き、毎回読み込むこと。

• 実装は「13. 実装タスク」の順に進める。フェーズを飛ばさない。
• 各タスクの括弧内は要件ID。着手前に該当章を読むこと。
• 仕様がここに書かれていない場合は、推測で実装せず質問する。
• スコープ外（4章 Won't have）は、思いついても実装しない。
• 「デモだから」を理由に品質を落とす判断はしない。

姉妹プロジェクトとの関係 HIREBASE（求人）／ RELATE（顧客管理）／ CASTA（動画配信）／ FIELDPIN（位置情報）に続く5本目。並べて「同じテンプレ」と思われた時点で失敗。 HIREBASE＝明朝・白・余白（読ませる）／ RELATE＝ゴシック・白・高密度（操作させる）／ CASTA＝ダーク・無彩色・モーション抑制（見せる）／ FIELDPIN＝地図全画面・大型UI（現場で使わせる）／ KANADE＝アートワークの色に画面が染まる・モーションが音に同期する（浸らせる）。 **特に CASTA との差別化に注意。**同じ「ダーク基調のメディアアプリ」だが、CASTA は「色を持たない・動かさない」、KANADE は「色が毎回変わる・音に合わせて動く」。真逆に振る。

目次

1. プロジェクト概要
2. 権利の壁 — この記事の核心
3. 記事への組み込み設計
4. アーキテクチャ方針
5. スコープ定義
6. ロールとデモ切替
7. 画面一覧とユーザーフロー
8. 機能要件
9. データ設計
10. デザイン要件
11. 技術要件・ディレクトリ構成
12. 非機能要件
13. 費用設計
14. 実装タスク
15. 受入基準

1. プロジェクト概要

背景と目的

「音楽アプリを作りたい」という相談の8割は、頭の中に Spotify / Apple Music がある。しかしそれは個人や中小企業には作れない。技術の問題ではなく、権利の問題として作れない（2章）。

一方で、実際に作れて、かつ需要があるものははっきりしている。

• 音楽教室・ボイストレーニングのレッスン音源配信
• ヨガ・瞑想・睡眠・作業用のBGM配信
• インディーレーベル・アーティストの自主配信プラットフォーム
• 社内向けの研修音声・ポッドキャスト
• 効果音・BGM素材の販売プラットフォーム

共通するのは、**「自分たちが権利を持つ音源を、会員に配信する」**という構造。KANADE はこの構造の実装デモとして作る。

プロダクト定義

プロダクトコンセプト

「聴いている間、アプリは邪魔をしない。」

音楽アプリの大半の時間、ユーザーは画面を見ていない。だからKANADEは、画面を見ていないときに強い——ロック画面で操作でき、通信が切れても止まらず、次の曲が途切れずに始まる。そして画面を見たときには、その曲の色に染まっている。

デモとしての成功条件

1. 記事の読者が、1タップで音を出せる
2. 画面を消しても再生が続き、ロック画面で操作できる — Webでここまでできることを体験させる
3. 曲間が途切れない — ギャップレス／クロスフェードが効いている
4. 画面遷移しても再生が止まらない — ミニプレーヤーが常駐している
5. 管理側も見られる — 音源のアップロード・配信管理・再生分析まで確認できる
6. 記事に戻れる／問い合わせできる — デモが行き止まりにならない

2. 権利の壁 — この記事の核心

この章は、実装要件であると同時に、記事本文の中核原稿である。 曖昧にしない。

なぜ個人・中小企業に Spotify は作れないのか

音楽を配信するには、2つの別々の権利の許諾が必要になる。

問題は後者。 管理団体に申請すれば済む話ではなく、レコード会社1社ずつと個別に契約する必要がある。大手配信サービスがこれを実現できているのは、事業規模と交渉力があるから。

つまり「既存のヒット曲を配信するアプリ」は、技術ではなく事業交渉の問題であり、開発費の見積もり以前の話。 ここを最初に伝えないと、依頼者は数百万円を払った後に「曲が入れられない」という現実に直面する。

では何が作れるのか

歌詞の扱い（見落とされやすい）

歌詞の表示にも、別途許諾が必要。 歌詞は著作物であり、アプリ内での表示は複製・公衆送信にあたる。歌詞表示サービスが管理団体と契約しているのはこのため。

自作の音源であっても、作詞者が別にいる場合は権利処理が要る。

本デモでの対応

記事に載せる際の注意： 権利まわりの記述は、「一般的な構造の説明」に留め、個別案件の可否を断定しないこと。 実際の権利処理は個別の契約内容に依存する。記事には「弁護士・管理団体への確認を推奨する」旨を明記すること。

3. 記事への組み込み設計

音声固有の制約：勝手に音を出せない

ブラウザはユーザー操作なしの音声再生をブロックする（Autoplay Policy）。これは制約であると同時に、守るべきマナーでもある。

記事を読んでいる最中に、突然音が鳴るのは最悪の体験。 埋め込みは「押されるまで一切音を出さない」ことを絶対条件にする。

配置方針（2段構え）

埋め込みモード（?embed=1）

<iframe
  src="https://kanade.souzoh-demo.com/play/track-001?embed=1"
  width="100%" style="aspect-ratio:16/7; border:0"
  loading="lazy"
  allow="autoplay"
  title="KANADE 音楽プレーヤーのデモ"></iframe>

記事本体のパフォーマンスを壊さない

「動画つき資料」との一体化

記事タイトルの「動画つき資料」を、別途用意せずデモの体験から作る。

• 動画：再生 → 画面を消してロック画面から操作 → 通信を切っても再生継続 → 管理画面で分析、までを3分で収録。「Webでもここまでできる」が一目で伝わる
• 資料：本要件定義から抜粋した「音源ライセンスのチェックリスト」と「配信コスト計算シート」をPDF化
• デモ内の「資料をダウンロード」からも取得でき、そこを問い合わせ導線に接続する

導線と計測

SEO上の扱い

4. アーキテクチャ方針

基本方針

バックエンドとデータベースを持たない。ただし音源だけは実在させる。

音源だけは実在させる理由

音が鳴らない音楽アプリのデモには、意味がない。再生ボタンを押して音が出るかどうかが、このデモの成否そのもの。

ただし実在させるのは配信であって、バックエンドではない。音声ファイルは静的ファイルなので、オブジェクトストレージに置くだけで配信できる。

音源素材の方針

エンコード仕様

入力: WAV / 高品質音源
出力:
  ├ 高音質  AAC 256kbps (.m4a)  ─┐
  └ 標準    AAC 128kbps (.m4a)  ─┘ どちらも単一ファイル（HLSにしない）
  ラウドネス: -14 LUFS に正規化（★曲ごとの音量差をなくす）
  波形: 512サンプルにダウンサンプリングしてJSON化
  ジャケット: 1000px / 300px / 80px の3サイズ + 代表色5色を抽出

エンコードとメタデータ生成は scripts/prepare-audio.sh（ffmpeg + ffprobe）としてリポジトリに含める。これ自体が記事の「方法」パートの説明材料になる。

ラウドネス正規化を必ず行うこと。 曲ごとに音量が違うアプリは、それだけで素人臭くなる。

配信先

Range リクエスト（206 Partial Content）への対応が必須。 シークができなくなる。

単一オーディオ要素の原則（最重要の設計判断）

アプリ全体で <audio> 要素を1つだけ生成し、レイアウトに常駐させる。

app/layout.tsx
  └ <PlayerProvider>            ← ここに <audio> が1つだけ存在する
       ├ <AudioEngine />        ← Web Audio のノードグラフもここ
       ├ {children}             ← 画面はここが差し替わるだけ
       └ <MiniPlayer />         ← 常駐。画面遷移しても消えない

• 画面遷移で再生が途切れないことが音楽アプリの最低条件（FR-108）
• ページごとに <audio> を作ると、遷移のたびに音が止まり、デモとして破綻する
• Web Audio のノードグラフ（GainNode / AnalyserNode）も同様に一度だけ構築する

FIELDPIN の「地図インスタンスは1つ」、CASTA の「hls.js の破棄」と同じ位置づけの構造要件。

永続化の範囲

擬似ディレイ は 150〜400ms。ただし再生・一時停止・シーク・曲送りにはディレイを入れない（音楽アプリで操作に遅延があるのは致命的）。

5. スコープ定義

リスナー向け機能

配信管理（運営）向け機能

共通・基盤

対象外（Won't have）

スコープリスク： 音楽アプリは「レコメンドAIも」「歌詞も全曲」「SNS連携も」と広がりやすい。特に推薦アルゴリズムは精度の合意形成に時間がかかる。 ジャンル・テンポ・お気に入りの一致という説明可能なルールで実装し、「なぜこの曲が推薦されたか」を画面上に表示することで、体験としての納得感を作る。

6. ロールとデモ切替

ロール定義

ロールを跨ぐ体験（必ず動くようにする）

1. 未ログインで有料曲を再生 → 30秒でペイウォール → 有料会員に切替 → 同じ位置から続きが再生される
2. 再生したまま画面遷移（ライブラリ→検索→プレイリスト）→ 一度も音が途切れない
3. 再生中に画面を消す → ロック画面に曲名とアートワークが出て、そこから曲送りできる
4. 有料会員でアルバムをダウンロード → 機内モードにする → オフラインで再生できる
5. 運営で楽曲を非公開に → リスナーに切替 → ライブラリから消えている
6. 自分が再生した曲が、運営の再生分析にカウントされ、完聴率に反映される

デモ切替バー（F-S01）

画面上部に常時表示する固定バー。埋め込みモードでは非表示。

• 現在のロール表示と4ロールの切替
• 「デモをリセット」ボタン（確認ダイアログ付き）
• 元記事へ戻るリンク
• 「本デモの音源は権利処理済みのものです」の注記（RGT-07）
• 「これはデモです」の明示

デザイン上の扱い： アプリ本体がアートワークの色に染まるため、切替バーはその影響を受けない固定の濃色帯とする。プロダクトのダイナミック配色に巻き込まない。

7. 画面一覧とユーザーフロー

全28画面。画面IDはディレクトリ構成と 1:1 で対応させる。

リスナー画面

管理画面

主要フロー

フローA：記事の読者が音に触れる（最重要）

SEO記事を読んでいる
   ↓
記事内の埋め込みプレーヤー（アートワーク + 再生ボタン。まだ何も読み込んでいない・音も出ない）
   ↓
再生ボタンを押す ── ここで初めて AudioContext を生成し、音源を取得
   ↓
再生開始（2秒以内）── 波形が動き、シークできる
   ↓
「全画面でデモを開く」→ 別タブでアプリ本体へ
   ↓
SC-001 ホーム ── ガイドツアーが3ステップで「試せること」を案内
   ↓
アルバムを開いて再生 → ★ 画面を遷移しても音が途切れない（ミニプレーヤー常駐）
   ↓
★ 画面を消す → ロック画面に曲名とアートワークが出る → そこから曲送りできる
   ↓
デモ切替バーで「運営」に切替 → SC-150 再生分析
   ↓  ★ たった今の再生が、完聴率のグラフに反映されている
資料ダウンロード or 元記事に戻る

フローB：ペイウォールと高音質・ダウンロード

SC-001 ホーム（未ログイン）── 有料バッジ付きの曲を選ぶ
   ↓
再生開始。プレーヤー上部に「無料プレビュー 残り0:23」
   ↓
30秒経過 ── フェードアウトして停止、ペイウォールがオーバーレイ表示
   ↓
SC-040 プラン比較 → SC-041 申込 → SC-042 完了
   ↓  ※ 決済処理は行わない。ロールが premium に変わる
★ 停止した0:30の位置から、そのまま続きが再生される
   ↓
SC-011 アルバム詳細 ──「ダウンロード」が有効になっている
   ↓
ダウンロード実行 ── ★ Cache API に実ファイルを保存（進捗表示）
   ↓
機内モードにする
   ↓
★ ダウンロード済みの曲が、オフラインで再生できる
   未ダウンロードの曲は「オフラインでは再生できません」と明示

フローC：運営が音源を公開する（ライセンス管理が肝）

SC-111 音源アップロード ── ファイルをドロップ
   ↓
変換進捗の再現
   解析中 → 変換中（256k / 128k）→ 波形生成 → ジャケット色抽出 → 完了
   ※ 一定確率で「変換失敗」を再現し、リトライ導線を見せる
   ↓
SC-112 楽曲編集 ── タイトル、アーティスト、アルバム、ジャンル、無料／有料
   ↓
公開しようとする
   ↓
★ ブロックされる：「ライセンス情報が未記入のため公開できません」
   ↓
SC-113 ライセンス管理
   取得元／ライセンス種別／許諾範囲（配信可・改変不可 等）／確認日／証跡URL
   ↓
記入完了 → 公開可能になる
   ↓
SC-114 歌詞編集 ── 再生しながらタイムスタンプを打つ
   ↓
公開
   ↓
【ロール切替：無料会員】
SC-001 ホームの「新着」に出現

8. 機能要件

8.1 プレーヤー（このデモの心臓部）

8.2 バックグラウンド再生とロック画面（Webの実力を示す部分）

8.3 キューとプレイリスト

8.4 ライブラリ・検索・レコメンド

8.5 オフライン再生

8.6 ビジュアライザー・歌詞

8.7 会員・ペイウォール

8.8 配信管理

8.9 再生分析

8.10 デモ基盤

9. データ設計

型定義（lib/types/）

// ---- コンテンツ ----
type Artist = {
  id: string
  name: string                  // ★ すべて架空（RGT-05）
  nameKana: string
  imageUrl: string
  bio: string
  albumIds: string[]
}

type Album = {
  id: string
  title: string
  artistId: string
  releaseDate: string
  coverUrl: string              // 1000px
  coverUrlSm: string            // 300px
  coverUrlXs: string            // 80px
  palette: string[]             // ★ ジャケットから抽出した代表色5色（10章のダイナミック配色）
  trackIds: string[]            // 並び順を保持
  genreIds: string[]
  isPublished: boolean
}

type Track = {
  id: string
  title: string
  albumId: string
  artistId: string
  trackNumber: number
  durationSec: number
  bpm: number                   // レコメンドのテンポ一致に使用
  genreIds: string[]
  // --- 配信情報（実在するファイルを指す） ---
  audioUrlHigh: string          // AAC 256kbps
  audioUrlStandard: string      // AAC 128kbps
  waveform: number[]            // ★ 512点。事前生成（AUD-07）
  loudnessLufs: number          // 正規化用
  // --- ギャップレス ---
  gaplessNextTrackId?: string   // ★ 切れ目なく繋がる次曲（AUD-06）
  // --- 公開・課金 ---
  access: 'free' | 'paid'
  previewSec: number            // 有料時のプレビュー秒数（既定30）
  status: 'draft' | 'published' | 'private'
  // --- 権利（★ 未記入では公開できない。FR-706） ---
  license: TrackLicense | null
  lyrics?: LyricLine[]
  playCount: number
  createdAt: string
}

type TrackLicense = {
  source: string                // 取得元（自社制作 / 提供元名）
  licenseType: string           // CC0 / CC BY / 商用ライセンス / 自社原盤 等
  scope: string                 // 許諾範囲（配信可・改変不可 等）
  evidenceUrl: string           // ライセンス文書のURL（RGT-03）
  confirmedAt: string           // 確認日
  confirmedBy: string
  note: string
}

type LyricLine = { atSec: number; text: string }
type Genre = { id: string; name: string; slug: string }

// ---- 会員・プラン ----
type Plan = {
  id: string
  name: string                  // 無料 / スタンダード / プレミアム
  priceMonthly: number
  accessScope: 'free_only' | 'all'
  maxQuality: 'standard' | 'high'
  canDownload: boolean          // ★ プランごとの機能差
  features: string[]
  sortOrder: number
}

type Member = {
  id: string
  name: string
  email: string
  avatarUrl: string
  role: 'guest' | 'free' | 'premium' | 'admin'
  planId: string
  status: 'active' | 'cancelled'
  createdAt: string
}

// ---- 再生状態（★ 永続化される中核） ----
type PlaybackState = {
  currentTrackId?: string
  positionSec: number
  isPlaying: boolean            // 復元時は false にする
  queue: QueueItem[]
  queueIndex: number
  repeat: 'off' | 'all' | 'one'
  shuffle: boolean
  shuffleOrder?: number[]       // 元順序に戻すため保持（FR-204）
  volume: number                // 0-1
  quality: 'high' | 'standard' | 'auto'
  crossfadeSec: 0 | 2 | 4 | 6
  loudnessNormalization: boolean
  sourceContext?: { type: 'album' | 'playlist' | 'artist' | 'search'; id: string }
}
type QueueItem = { id: string; trackId: string; addedBy: 'context' | 'manual' }

// ---- ユーザーデータ ----
type Playlist = {
  id: string
  ownerId: string
  name: string
  description: string
  coverUrl?: string             // 未設定ならジャケット4枚から自動生成（FR-206）
  trackIds: string[]
  isOfficial: boolean           // 運営作成
  isPublished: boolean
  createdAt: string
}
type Favorite = { id: string; memberId: string; targetType: 'track' | 'album'; targetId: string; addedAt: string }
type PlayHistory = { id: string; memberId: string; trackId: string; playedAt: string; completedRatio: number }

// ---- オフライン ----
type DownloadItem = {
  id: string
  trackId: string
  memberId: string
  quality: 'high' | 'standard'
  sizeBytes: number
  state: 'queued' | 'downloading' | 'done' | 'failed'
  progress: number              // 0-100
  cacheKey: string              // ★ Cache API のキー（FR-402）
  downloadedAt?: string
}

// ---- 再生イベント（分析の元データ） ----
type PlayEvent = {
  id: string
  trackId: string
  memberId: string
  type: 'start' | 'progress' | 'complete' | 'skip' | 'pause' | 'seek'
  positionSec: number
  quality: 'high' | 'standard'
  device: 'desktop' | 'mobile' | 'tablet'
  isBackground: boolean         // ★ バックグラウンド再生だったか（EMB-14）
  isOffline: boolean
  occurredAt: string
}

// ---- 分析（集計値。ストアに保存せず lib/calc で算出） ----
type TrackStats = {
  trackId: string
  plays: number
  uniqueListeners: number
  completionRate: number        // 完聴率
  skipRate: number              // スキップ率
  avgSkipAtSec: number          // ★ 平均スキップ秒数（FR-802）
  byHour: number[]              // 24要素。時間帯別
  byDevice: Record<'desktop'|'mobile'|'tablet', number>
  byQuality: Record<'high'|'standard', number>
}

// ---- アップロード（擬似） ----
type UploadJob = {
  id: string
  fileName: string
  sizeBytes: number
  stage: 'uploading' | 'analyzing' | 'transcoding' | 'waveform' | 'palette' | 'done' | 'failed'
  progress: number
  errorReason?: string
  linkedTrackId?: string        // 完了時に既存素材へ紐付け（FR-703）
  createdAt: string
}

シードデータ（lib/seed/）

シード作成のルール（品質を左右する）

• アーティスト名・アルバム名・曲名は架空で、かつ実在を想起させないこと（RGT-05）
• 曲名を「Track 01」のようなダミーにしない。 世界観のある名前を付ける。ここが手抜きだとアプリ全体が安っぽくなる
• ジャンルとBPMに幅を持たせる。 全曲が似ていると、レコメンドもプレイリストも意味を持って見えない
• 再生イベントは自然な分布で生成する。 冒頭10秒でのスキップが一定割合あり、完聴する曲としない曲がある。曲ごとにパターンを変える
• スキップされやすい曲を意図的に作る。 全曲が完聴されると、分析画面が無意味になる
• 時間帯別の再生に山を作る（通勤時間帯・夜間）。フラットだと「いつ聴かれるか」の分析が死ぬ
• 日付は現在日時からの相対で生成する。固定日付を埋め込まない
• ペルソナに「途中まで聴いた曲」を持たせる（起動直後の「続きから聴く」が空にならないように）
• ライセンス未記入の楽曲を1〜2曲、下書き状態で用意する（フローCの実演用）

ストアとリポジトリ

lib/
├── types/ seed/
├── audio/                      # ★ オーディオの中核。ここだけが Web Audio を触る
│   ├── engine.ts               # AudioContext / GainNode / AnalyserNode のグラフ構築
│   ├── player.ts               # 再生・停止・シーク・曲送り
│   ├── crossfade.ts            # クロスフェードとギャップレス
│   ├── loudness.ts             # ラウドネス正規化のゲイン計算
│   ├── media-session.ts        # Media Session API
│   └── visualizer.ts           # AnalyserNode からの描画データ生成
├── offline/
│   ├── cache.ts                # Cache API のラッパー（FR-402）
│   └── download-queue.ts
├── calc/                       # 完聴率・スキップ率・レコメンド・パレット適用
├── query/                      # 検索・絞り込み
├── store/  { session, content, playback, library, download, ui }
└── repo/                       # ★ コンポーネントが触るのはここだけ
    ├── _delay.ts _scope.ts
    ├── tracks.ts albums.ts artists.ts playlists.ts
    ├── members.ts plans.ts downloads.ts uploads.ts analytics.ts

リポジトリ層とオーディオ層の規約（厳守）

• リポジトリの全メソッドを async で定義。戻り値は { ok: true; data: T } | { ok: false; error: string } に統一
• コンポーネントから Zustand ストアを直接参照しない
• AudioContext と <audio> を lib/audio/ 以外で触らない。 コンポーネントは usePlayer() フック経由でのみ操作する
• 再生可否の判定（resolveAccess(track, role)）は lib/repo/_scope.ts に集約する。 コンポーネント側で role === 'premium' のような分岐を書かない（FR-908）
• 派生値（完聴率・スキップ率・パレット適用色）はストアに保存せず lib/calc/ で算出する
• 再生・一時停止・シーク・曲送りに擬似ディレイを入れない

// lib/repo/_scope.ts — 実案件では署名付きURL発行・DRM に置き換わる箇所
export function resolveAccess(track: Track, member: Member, plan: Plan): AccessResult {
  if (track.access === 'free') return { kind: 'full', quality: plan.maxQuality }
  if (member.role === 'premium' || member.role === 'admin')
    return { kind: 'full', quality: plan.maxQuality }
  return { kind: 'preview', limitSec: track.previewSec }
}
export function canDownload(plan: Plan): boolean { return plan.canDownload }

10. デザイン要件

アートディレクション

「アートワークの色に、画面を染める」

音楽アプリは、聴いている間ほとんど見られない。だから見られる瞬間に強い印象を残す必要がある。KANADE は、**再生中の曲のジャケットから抽出した色が、画面全体に静かに広がる。**曲が変わると色が変わる。

• ベースは暗いが、無彩色ではない。 現在の曲のパレットで背景が染まる
• モーションは音に同期する。 ビジュアライザー、波形、再生中のアイコンの脈動
• アートワークが最大の要素。 全画面プレーヤーでは画面の半分以上をジャケットが占める
• ミニプレーヤーは常に画面下に。 音楽が鳴っている間、それが見えていることが安心につながる

CASTA との差別化（特に注意） どちらもダーク基調のメディアアプリだが、方向は真逆にする。 CASTA：色を持たない（無彩色）／モーションを抑える／UIが消える KANADE：色が曲ごとに変わる／モーションが音に同期する／UIが色に染まる 並べたときに「同じダークテーマ」と見えたら失敗。

カラートークン

:root {
  /* 静的な基盤 */
  --bg-deep:    #08090C;   /* 最下層 */
  --bg-base:    #101218;   /* ページ背景（この上にパレットが乗る） */
  --bg-raised:  #191C24;   /* カード */
  --bg-overlay: #23262F;   /* モーダル・シート */

  --fg-high:    #F4F5F7;
  --fg-mid:     #A6ACB8;
  --fg-low:     #6E7480;
  --border:     #262A33;

  /* ★ ダイナミック：現在の曲のジャケットから抽出して JS で更新する */
  --art-1: #4A5A8C;   /* 主要色 */
  --art-2: #7A5A6E;   /* 副次色 */
  --art-3: #2A3350;   /* 暗色 */
  --art-accent: #C8A45E;  /* アクセント（再生・進捗・現在地） */

  /* 派生グラデーション */
  --wash: radial-gradient(120% 80% at 50% 0%,
            color-mix(in srgb, var(--art-1) 28%, transparent) 0%,
            transparent 70%);
}

ダイナミック配色のルール（重要）

タイポグラフィ

CASTA は 700 まで、KANADE は 900 を使う。 極太で詰めたタイポグラフィが、音楽アプリらしい強さを作る。

レイアウトとスペーシング

主要コンポーネント仕様

モーション

prefers-reduced-motion: reduce 時は、パレット切替を即時にし、脈動・音波・ビジュアライザーを停止すること。

アクセシビリティ（WCAG 2.1 AA）

ライティング規約

11. 技術要件・ディレクトリ構成

技術スタック（固定・勝手に変更しない）

上記以外のライブラリを入れる前に必ず提案し、承認を得ること。特に音声再生ライブラリ（howler.js / Tone.js / wavesurfer.js）の導入は禁止。

ディレクトリ構成

/
├── CLAUDE.md
├── app/
│   ├── layout.tsx                  # ★ PlayerProvider / MiniPlayer をここに常駐させる
│   ├── page.tsx                    # SC-001 ホーム
│   ├── play/[trackId]/page.tsx     # SC-003（?embed=1）
│   ├── albums/[id]/  artists/[id]/ playlists/
│   ├── library/  search/  history/  downloads/
│   ├── settings/  plans/
│   ├── admin/                      # SC-100〜150
│   └── dev/components/
├── components/
│   ├── player/                     # ★ 最重要
│   │   ├── PlayerProvider.tsx      # <audio> は アプリ全体でここに1つだけ
│   │   ├── MiniPlayer.tsx          # 常駐
│   │   ├── FullPlayer.tsx          # オーバーレイ
│   │   ├── WaveformSeekBar.tsx
│   │   ├── QueueSheet.tsx
│   │   ├── LyricsView.tsx
│   │   ├── Visualizer.tsx
│   │   ├── Paywall.tsx
│   │   └── usePlayer.ts            # ★ コンポーネントはこのフック経由でのみ操作する
│   ├── catalog/                    # AlbumCard, TrackRow, ArtistCard, Grid
│   ├── domain/                     # DownloadBadge, OfflineBanner, LicenseForm, UploadStepper, StatsChart
│   ├── demo/                       # RoleSwitcher, ResetButton, GuideTour, BackToArticle
│   └── layout/
├── lib/
│   ├── types/ seed/ store/ repo/
│   ├── audio/                      # ★ Web Audio を触る唯一の場所
│   ├── offline/                    # Cache API
│   ├── calc/ query/ validation/ utils/
├── scripts/
│   └── prepare-audio.sh            # ffmpeg エンコード・波形生成・パレット抽出
├── docs/
│   └── audio-license.md            # ★ 全曲のライセンス記録（RGT-02）
├── e2e/
└── public/

コーディング規約

• TypeScript strict。any 禁止
• AudioContext と <audio> を lib/audio/ と PlayerProvider 以外で触らない
• コンポーネントは usePlayer() フック経由でのみプレーヤーを操作する
• コンポーネントから Zustand ストアを直接参照しない。必ず lib/repo/ 経由
• 再生可否を role === 'premium' のようにコンポーネントに書かない。 resolveAccess() を使う
• AudioContext はユーザー操作を起点にのみ生成する（FR-102）
• MediaElementAudioSourceNode は1つの <audio> に対して1回しか作れない。 再生成しようとするとエラーになるため、必ず1度だけ構築して使い回すこと
• ビジュアライザーの requestAnimationFrame は、再生停止時・アンマウント時に必ずキャンセルすること
• 高さは 100dvh を使う。100vh を使わない
• コミットは1タスクごと。メッセージに要件IDを含める 例：feat(player): クロスフェードをGainNodeで実装 (FR-106)

12. 非機能要件

セキュリティ・権利

実案件への転用時の注意（デモ本体の要件ではない。商談で聞かれた際に説明できるよう記録）

• 本デモの音源URLは公開されており、URLを知る第三者が直接ダウンロードできる。 実サービスでは署名付きURL（有効期限付き）や暗号化配信が必要
• 有料コンテンツを扱う場合、特定商取引法に基づく表記、解約条件の明示が必要
• 権利者への使用料の分配が必要な場合、再生回数の正確な記録と集計の仕組みが要る。 これは開発スコープに大きく影響する
• 会員情報は個人情報保護法の対象
• 本デモは会員情報をサーバーに送信しないため、これらの義務は発生しない。「デモである」旨は画面上に常時明示する

13. 費用設計

記事の主題の半分は「費用」。この章は実装要件であると同時に、記事本文の原稿素材でもある。

音楽アプリの費用は、他のアプリと構造が違う

⓪を無視して①だけ見積もると、事業が成立しない。 記事ではこの順序で説明する。

⓪ 音源のライセンス費（最大の分岐）

「再生数に応じた分配」を採用する場合、集計の正確性が事業リスクになる。 何を1再生と数えるか（30秒以上か、完聴か）を最初に決める必要があり、これは仕様であり費用でもある。

③ 変動運用費の計算式

月間転送量(GB) = ビットレート(kbps) ÷ 8 ÷ 1024 × 平均再生秒数 × 月間再生数 ÷ 1024

例：標準音質（128kbps）／ 平均再生 3分（180秒）／ 月間 50,000再生
  = 128 ÷ 8 ÷ 1024 × 180 × 50,000 ÷ 1024
  ≈ 134 GB/月

動画より1再生あたりは軽い。ただし音楽はリピート率が圧倒的に高い。 同じ曲を何十回も聴かれるため、再生数の伸び方が動画とは違う。

そしてオフラインダウンロードは、転送量を減らす機能でもある。 1回ダウンロードすれば、以降の再生で転送が発生しない。FR-401〜409 は機能要件であると同時にコスト最適化施策であり、記事ではこの視点を示す。

開発費の目安（スコープ別）

Webで足りるか、ネイティブが必要か

位置情報アプリ（FIELDPIN）と違い、音楽アプリはWebでかなりのことができる。 これは記事の重要な発見になる。

判断の目安： 車載連携と大量のオフライン保存が必須でなければ、Webで十分。開発費は大きく下がる。

デモ自体の運用コストを実測して記事に載せる

記事に載せる際の注意： 音源ライブラリや配信サービスの単価は変動するため、この文書に金額を書き込まない。 記事執筆時点で公式の料金ページ・規約を確認し、確認日を明記して掲載すること。 特にライセンス条件は変更されることがあるため、「必ず最新の規約を確認すること」を記事に明記する。

14. 実装タスク

この順に進める。フェーズを飛ばさない。 完了時は [x] に更新する。

Phase 0 — 基盤と音源（3日）

0-1. 初期化

• Next.js 15 / TypeScript strict / App Router / Tailwind で初期化
• ESLint / Prettier / husky（pre-commit で lint + typecheck）
• 11章のディレクトリ構成を作成

0-2. 音源の準備（先にこれを終わらせる。素材がないとプレーヤーが作れない）

• 使用する音源を確定し、2章 RGT-01〜07 の権利要件を満たすことを確認する
• docs/audio-license.md に全曲のライセンスを記録（取得元・種別・許諾範囲・証跡URL・確認日）(RGT-02)
• scripts/prepare-audio.sh を作成（AAC 256k/128k 変換、-14 LUFS 正規化、波形512点のJSON化、ジャケット3サイズ + パレット5色抽出）
• 24〜36曲をエンコード。ジャンルとBPMに幅を持たせる(AUD-04)
• ギャップレス実演用に、切れ目なく繋がる2曲を1組以上用意(AUD-06)
• Cloudflare R2 にアップロードし、CDN経由で配信できることを確認
• Range リクエスト（206）が返ることを確認（NFR-13）
• CORS と Cache-Control を設定
• 架空のアーティスト・アルバム・曲名を作成（ダミー名にしない、RGT-05）

0-3. 型とシード

• lib/types/ に9章の型定義をすべて実装
• lib/seed/ の全ファイル
• playEvents.ts を自然な分布で生成。 冒頭10秒スキップが一定割合、曲ごとに完聴率のパターンを変える
• スキップされやすい曲を意図的に作る。 時間帯別に山を作る
• ペルソナに「途中まで聴いた曲」を持たせる
• ライセンス未記入の下書き楽曲を1〜2曲用意（フローCの実演用）

0-4. ストアとリポジトリ

• lib/store/{session,content,playback,library,download,ui}.ts を Zustand + persist で実装
• lib/repo/_scope.ts に resolveAccess() と canDownload() を実装（FR-908）
• lib/repo/ の全モジュール。再生系にディレイを入れない
• lib/calc/ に 完聴率・スキップ率・レコメンド・パレット補正 を実装
• resolveAccess() と calc の単体テストをこの時点で書く

0-5. デザインシステム

• app/globals.css にカラートークンを CSS 変数で定義（静的 + ダイナミック）
• lib/calc/palette.ts：抽出色から --art-* を算出し、コントラスト比4.5:1を保証する補正を実装（CLR-04）
• 全アルバムのパレットでコントラスト比を実測して検証する（A11Y-01）
• tailwind.config.ts から CSS 変数を参照するよう theme を拡張
• フォント（Noto Sans JP 400/500/900 / Roboto Mono）。時間に tabular-nums
• 100dvh とセーフエリアの対応
• shadcn/ui を導入し、ダークトークンに合わせて上書き
• 共通コンポーネント：AlbumCard / TrackRow / EmptyState / Skeleton / Badge / Grid
• prefers-reduced-motion の対応
• /dev/components にコンポーネントカタログを作成

0-6. デモ基盤

• RoleSwitcher（4ロール）(FR-901)
• デモ切替バー。ダイナミック配色の影響を受けない固定の濃色帯（CLR-06）
• 「デモをリセット」（localStorage + Cache API をクリア）(FR-902)
• 元記事リンク・資料ダウンロード・権利注記(FR-904, FR-905)

Phase 0 完了チェック

• R2 の音声URLをブラウザで直接開いて再生でき、シークできる
• docs/audio-license.md に全曲が記録されている
• どのアルバムのパレットでも、テキストのコントラスト比が4.5:1以上
• /dev/components で全コンポーネントがトークン通りに表示される

Phase 1 — プレーヤー（5日・最重要フェーズ）

1-1. オーディオエンジン

• PlayerProvider.tsx：アプリ全体で <audio> を1つだけ生成し、レイアウトに常駐させる（FR-108）
• lib/audio/engine.ts：AudioContext → MediaElementAudioSourceNode → GainNode → AnalyserNode → destination のグラフ構築
• AudioContext をユーザー操作起点でのみ生成（FR-102）
• MediaElementAudioSourceNode は1度だけ作り、使い回す（再生成でエラーになるため）
• usePlayer.ts フック：コンポーネントからの唯一の操作口
• 再生／停止／シーク／音量／曲送り戻し（3秒以降は曲頭へ）(FR-101)
• リピート・シャッフル（現在曲を先頭固定、解除で元順序復帰）(FR-103, FR-204)
• ラウドネス正規化（GainNode で LUFS 差を補正）(FR-107)
• エラー表示（原因を区別 + 再試行）(FR-111)

1-2. ギャップレスとクロスフェード

• 次曲の事前バッファ（FR-105）
• lib/audio/crossfade.ts：2つ目の <audio> を裏で用意し、GainNode で音量を交差（FR-106）
• クロスフェード秒数の設定（0/2/4/6秒）。0秒でギャップレス動作
• 曲間の無音が50ms以下であることを実測（NFR-03）

1-3. UI

• MiniPlayer.tsx：画面下部常駐。上端に極細進捗バー。コンテンツ側に余白を確保（NFR-06）
• FullPlayer.tsx：下から迫り上がる。ジャケットをミニ↔全画面で共有要素として拡大縮小
• WaveformSeekBar.tsx：事前生成512点の描画、再生済みの塗り分け、ドラッグ中の拡大
• role="slider" と aria-valuetext（A11Y-04）
• QueueSheet.tsx：ドラッグ並び替え、個別削除、「次に再生」(FR-201, FR-202)
• ダイナミック配色の適用：曲変更で --art-* を600msかけて補間（CLR-01, CLR-02）
• 再生位置・キュー・モード・音量の永続化と復元（FR-110）
• キーボードショートカット（FR-115）

1-4. バックグラウンド再生とロック画面

• lib/audio/media-session.ts：メタデータ設定（曲名・アーティスト・アルバム・アートワーク）(FR-152)
• アクションハンドラ（play / pause / nexttrack / previoustrack / seekto）(FR-153, FR-154)
• positionState の更新（FR-155）
• 曲変更時のメタデータ更新（FR-156）
• タブ非表示・画面消灯でも再生継続を確認（FR-151）
• オーディオフォーカス喪失時の一時停止（FR-157）
• 実機（iOS / Android）でロック画面の表示と操作を検証する

1-5. 埋め込みモード

• SC-003 埋め込みモード（FR-159, EMB-02〜07）
• アートワーク + 再生ボタンのみの初期表示。押下で音源取得
• Media Session API を使わない（FR-159）
• リアルタイム解析を行わず、事前波形のハイライトのみ（FR-504, EMB-07）
• タブ非表示で一時停止（EMB-06）
• 初期バンドル 60KB以下を実測

Phase 1 完了チェック

• 再生ボタン押下から1.5秒以内に音が出る（NFR-01）
• 曲間に無音が知覚できない（ギャップレス、NFR-03）
• 画面を遷移しても一度も音が途切れない（FR-108）
• 実機で画面を消しても再生が続き、ロック画面から操作できる（FR-151〜153）
• 30曲を連続再生してもメモリが単調増加しない（NFR-10）
• 埋め込みモードで自動再生が起きず、初期バンドルが60KB以下

Phase 2 — ライブラリとペイウォール（4日）

2-1. カタログ

• SC-001 ホーム（続きから聴く、最近再生、おすすめ、新着、公式プレイリスト）(FR-209)
• SC-010 ライブラリ（4タブ）(FR-301)
• SC-011 アルバム詳細 / SC-012 アーティスト詳細
• SC-020 検索（表記ゆれ吸収、種別グループ化、URL同期）(FR-302〜304)
• SC-021 ジャンル一覧
• レコメンドのルールベース実装と「なぜ推薦されたか」の表示（FR-305, FR-306）
• トラック行のコンテキストメニュー（FR-307）
• 再生中トラック行の音波アニメーション + 「再生中」テキスト（A11Y-06）

2-2. プレイリスト・お気に入り

• SC-013 / SC-014 プレイリスト詳細・作成編集（FR-205）
• カバーの自動生成（ジャケット4枚）（FR-206）
• SC-015 お気に入り（FR-207）
• SC-030 再生履歴（FR-208）
• アルバム・プレイリスト再生時のキュー置換（警告なく消さない）(FR-203)

2-3. ペイウォール

• 有料バッジ表示（FR-601）
• プレビュー制限：30秒でフェードアウトして停止（FR-602）
• 残り時間の常時表示（FR-603）
• Paywall.tsx：オーバーレイ、プラン概要、CTA、閉じる導線、フォーカストラップ（FR-604, A11Y-09）
• SC-040〜042 プラン比較・申込・完了（FR-606〜608）
• 加入後、停止位置から続きを再生（FR-605）
• SC-043 契約状況、解約（FR-609）

2-4. 設定

• SC-032 再生設定（クロスフェード・音質・自動再生・ラウドネス正規化）(FR-112, FR-121)
• SC-033 スリープタイマー（5秒フェードアウト）(FR-113)

Phase 2 完了チェック

• フローBの前半が完走する（プレビュー → ペイウォール → 加入 → 続きから再生）
• 6章「ロールを跨ぐ体験」の1と2が動作する
• 検索・ライブラリを行き来しても再生が途切れない

Phase 3 — オフラインとPWA（3日）

• Service Worker / PWA マニフェスト（FR-409）
• lib/offline/cache.ts：Cache API に実際の音声ファイルを保存（FR-402）
• ダウンロード実行（有料会員のみ）と進捗表示、中断・再開（FR-401, FR-403）
• オフライン時にダウンロード済みの曲が実際に再生できること（FR-404）
• オフライン時の未ダウンロード曲の扱いと絞り込み導線（FR-405）
• SC-031 ダウンロード管理（一覧・容量・削除）(FR-406)
• 容量上限の警告（FR-407, NFR-14）
• オフラインバナー（FR-408）
• 解約時のダウンロード再生不可（FR-609）
• 「デモをリセット」で Cache もクリアされることを確認（FR-902）

Phase 3 完了チェック

• フローBの後半が完走する（ダウンロード → 機内モード → オフライン再生）
• 6章「ロールを跨ぐ体験」の4が動作する
• PWA としてホーム画面から起動でき、オフラインでも動く

Phase 4 — ビジュアライザー・歌詞・配信管理（4日）

4-1. ビジュアライザーと歌詞

• Visualizer.tsx：AnalyserNode からスペクトラム／波形を Canvas 描画（FR-501）
• 60fps維持、不足時は簡易表示へ自動フォールバック（FR-502, NFR-09）
• prefers-reduced-motion で既定OFF、手動OFFも可（FR-503）
• requestAnimationFrame の確実なキャンセル
• LyricsView.tsx：現在行ハイライト、自動スクロール、タップでジャンプ（FR-505, FR-506）
• 歌詞がない曲ではタブを出さない（FR-507）

4-2. 配信管理

• SC-100 管理ダッシュボード
• SC-111 音源アップロード：変換進捗の段階再現（FR-701, FR-702）
• 完了後は既存素材に紐付け。デモである旨を明示（FR-703）
• 変換失敗の再現とリトライ（FR-704）
• SC-112 楽曲編集（FR-705）
• SC-113 ライセンス管理。未記入では公開できないバリデーション（FR-706）
• SC-110 楽曲一覧でライセンス未記入を警告表示・絞り込み（FR-707）
• 公開設定と、非公開でリスナー側から即座に消えること（FR-708）
• SC-114 歌詞編集（再生しながらタイムスタンプ打ち込み）(FR-709)
• SC-120 アルバム管理（dnd-kit で並び替え、キーボード対応）(FR-710)
• SC-121 アーティスト管理 / SC-130 公式プレイリスト（FR-711, FR-712）
• SC-140 会員・プラン管理
• 一括操作（FR-713）

Phase 4 完了チェック

• フローCが完走する（アップロード → ライセンス記入で公開解禁 → 歌詞 → 公開 → リスナー側に出現）
• 6章「ロールを跨ぐ体験」の5が動作する
• ライセンス未記入の楽曲が絶対に公開できない

Phase 5 — 分析・記事統合・仕上げ（3日）

5-1. 再生分析

• SC-150 再生数・総再生時間・ユニークリスナー（期間指定）(FR-801)
• 完聴率・スキップ率・平均スキップ秒数（FR-802）
• 曲別・アルバム別・アーティスト別ランキング（FR-803）
• 時間帯別の再生数（FR-804）
• デバイス別・音質別（FR-805）
• デモ中の再生が分析に反映されること（FR-806）
• CSVエクスポート（FR-807）

5-2. 記事統合

• 記事側の埋め込みコードを作成し、実際の記事ページで動作確認（EMB-01〜07）
• 記事を読んでいるだけで音が鳴らないことを、複数ブラウザで確認
• 記事の Core Web Vitals を埋め込み前後で比較検証
• 「デモを開く」カードの設置
• 資料PDF（ライセンスチェックリスト・費用計算シート）の作成とダウンロード導線（F-S03）
• 元記事リンク・問い合わせ導線（EMB-10, EMB-11）
• GA4 イベント設定。bg_play と offline_play を必ず含める（EMB-12, EMB-14）
• ?embed=1 を noindex に（EMB-21）
• デモ本体の title / description / OGP（EMB-20）
• 記事側に VideoObject と HowTo の構造化データ。MusicRecording は使わない（EMB-23, EMB-24）

5-3. 体験の総点検

• 6章「ロールを跨ぐ体験」の6パターンをすべて手動で確認
• 全28画面を開き、空の画面が1つもないことを確認
• 実機（iOS Safari / Android Chrome）でのバックグラウンド再生とロック画面操作を再検証
• ガイドツアーを実装（FR-909）

5-4. アクセシビリティ監査

• axe-core を全画面に実行し、Critical / Serious を0件に
• 全アルバムのパレットでコントラスト比を再実測（A11Y-01, CLR-04）
• キーボードのみで全画面・全プレーヤー操作を完遂
• スクリーンリーダーで再生状態の変化が読み上げられることを確認（A11Y-05）
• フォントサイズ200%での操作確認（A11Y-11）

5-5. パフォーマンス

• Recharts を動的import に切り出し、初期バンドルを200KB以下に（NFR-08）
• 再生開始1.5秒以下、曲送り500ms以下、曲間無音50ms以下を実測（NFR-01〜03）
• ビジュアライザーの60fpsを実測（NFR-09）
• 30曲連続再生でのメモリ推移を計測（NFR-10）
• Lighthouse で Performance 90 / Accessibility 95（NFR-11）

5-6. 公開と記録

• Playwright で フローA・B・C の E2E
• Vitest：lib/audio lib/calc _scope のカバレッジ80%以上
• /dev/components を本番で非公開に
• Vercel へデプロイ、R2 の転送量アラートを設定（COST-03）
• 転送量・費用・ダウンロードによる削減効果の記録を開始（COST-01, COST-04）
• 解説動画（3分）の収録：再生 → 画面消灯でロック画面操作 → 通信を切ってオフライン再生 → 管理画面で分析
• 各フェーズのキャプチャを整理し、記事の「方法」パートの素材にまとめる

合計 22営業日（約4.5週間）／1名専任 + レビュー体制。

工数配分の意図： Phase 1 に5日を割いているのは、ギャップレス再生・クロスフェード・バックグラウンド再生・ロック画面操作が、この記事の主張（「Webでここまでできる」）そのものだから。既製ライブラリを貼れば1日で音は出るが、それでは何も証明できない。 Phase 0 の音源準備を最優先にすること。権利確認が終わらないと、1行も書けない。

15. 受入基準

1. 8章の優先度 P1 の要件がすべて実装されていること
2. 7章の主要フローA・B・Cが、エンドツーエンドで完走すること
3. 6章「ロールを跨ぐ体験」の6パターンがすべて動作すること
4. 再生ボタン押下から1.5秒以内に音が出ること
5. 画面を遷移しても再生が一度も途切れないこと（<audio> がアプリ全体で1つだけであること）
6. 曲間の無音が知覚できないこと（ギャップレス）。クロスフェードが設定秒数どおりに動作すること
7. 実機で、画面を消しても再生が続き、ロック画面から曲名・アートワークの確認と操作ができること
8. 有料会員でダウンロードした曲が、オフラインで実際に再生できること（Cache API に実ファイルが保存されていること）
9. ペイウォールが動作し、加入後に停止位置から続きが再生されること
10. ライセンス情報が未記入の楽曲を、公開できないこと
11. docs/audio-license.md に全楽曲・全画像のライセンスが記録されていること
12. どのアルバムのパレットでも、テキストのコントラスト比が 4.5:1 以上であること
13. 30曲を連続再生してもメモリが単調増加しないこと
14. 埋め込みモードで自動再生が一切起きず、初期バンドルが60KB以下であること
15. デモ中の再生が再生分析に反映され、完聴率・スキップ率が意味のある値で表示されること
16. 全28画面のいずれにも空の状態がなく、リアルなコンテンツが表示されていること
17. axe-core で Critical / Serious の指摘が0件であること
18. データアクセスがすべて lib/repo/ を経由し、AudioContext が lib/audio/ 以外で触られていないこと
19. HIREBASE / RELATE / CASTA / FIELDPIN と並べたときに、明確に別のプロダクトとして見えること。特に CASTA と混同されないこと

判断に迷ったときのルール

1. 仕様がこの文書にない場合は、実装せずに質問する。 推測で作らない
2. 権利確認を後回しにしない。 ライセンスが確認できない音源は、1曲たりとも使わない
3. 既製の音声ライブラリ（howler.js / Tone.js / wavesurfer.js）を導入しない。 自前実装であることがこのデモの価値
4. <audio> はアプリ全体で1つだけ。 画面遷移で音が途切れたら設計が間違っている
5. AudioContext はユーザー操作起点でのみ生成する。 ページ読み込み時に作らない
6. MediaElementAudioSourceNode は1度だけ作る。 再生成はエラーになる
7. ダイナミック配色でコントラスト比を割らせない。 見た目の美しさより可読性が優先
8. ビジュアライザーの requestAnimationFrame を必ずキャンセルする。このアプリで最も起きやすい不具合はメモリリーク
9. スコープ外（5章 Won't have）は実装しない
10. 「デモだから」を理由に品質を落とす判断はしない
11. CASTA のトークン・コンポーネントをコピーしない。 同じダークテーマでも方向は真逆