﻿---
title: "設定リファレンス：音楽プレーヤー"
description: "音楽のスイッチ、曲項目、既定値、ロード、多言語文面、検証と再開の制約を実装に基づいて説明します。"
url: "https://demo.anglefeint.com/ja/blog/config-music/"
language: "ja"
author: "Anglefeint"
published: "2026-11-13T00:00:00.000Z"
updated: "2026-11-14T00:00:00.000Z"
---

# 設定リファレンス：音楽プレーヤー

最初の曲は[音楽設定ガイド](https://demo.anglefeint.com/ja/blog/starter-guide-3-comments-about-and-theme-toggles/)、設定ファイルは[インストール](https://demo.anglefeint.com/ja/blog/starter-guide-1-configure-your-site/)、他モジュールは[総合案内](https://demo.anglefeint.com/ja/blog/config-reference/)を参照してください。

`src/site.config.ts` の `theme.music` に指定します。既定では無効、プレイリストは空、曲は付属しません。以下はデモ個人設定ではなくパッケージ既定値です。

## theme.music.enabled：プレーヤーのスイッチ

*   **型 / 既定値：** boolean / false。
*   **状態と役割：** 有効。true かつ有効な曲が1件以上なら標準の共通枠に描画します。
*   **制約：** true だけで曲なしなら表示しません。無効時は有効な実行リストへ入れず曲別検証もスキップしますが、設定・public の音声を削除したり直接アクセスを制限したりしません。
*   **例：** `theme: { music: { enabled: false } }`。

全体共通設定で、ホーム・言語別スイッチではありません。共通枠を使う標準ページは同じリストを共有し、ホーム専用ではありません。独自ページへの接続はそのページ次第です。

## theme.music.tracks：曲一覧

*   **型 / 既定値：** MusicTrack\[\] / \[\]。各曲の3項目は下表です。
*   **状態と役割：** 音楽有効時に配列順で表示・切替します。公開の件数上限はありません。
*   **制約：** 有効時は配列必須。空配列も有効ですが実プレーヤーは無効になります。配列は既定・旧リストに追加でなく全置換し、追加時は残す曲も含めます。
*   **値の例：** \[{ title: ‘我的一首歌’, artist: ‘作者’, src: ‘`/music/my-song.mp3`’ }\]。

曲名・作者・URL はこの全体配列で、i18n 文面ではありません。言語切替で曲は変わりません。他サービスのプレイリストオブジェクトや共有 URL をそのまま指定しないでください。

### 各曲の項目

接頭辞は `theme.music.tracks[]` です。「なし」は独自項目の自動補完がない意味です。

| 項目 | 型 / 既定値 | 状態・役割・制約 | 例 |
| --- | --- | --- | --- |
| title | 必須 string / なし | 条件付き：主表示、折り畳み見出し、一覧の曲名。非空必須で前後空白除去。空白だけはエラー、ファイル名・音声タグから生成しません。 | ‘私の一曲’ |
| artist | 任意 string / 未指定、‘’ に正規化 | 主表示と一覧の作者。指定時 string 必須、前後空白を除去。サイト作者や音声メタ情報から補いません。 | ‘著者’ |
| src | 必須 string / なし | 単一 / または小文字 https:// から始め、空白・逆斜線不可。HTTPS は URL 解析可能なこと。存在・音声内容は検証しません。 | ‘/music/my-song.mp3’ |

title・artist はプレーンテキストで Markdown・HTML は解析しません。カバー、歌詞、長さ、アルバム、独立 ID、曲ごとの音量の公開項目はありません。

src の制約を区別してください。

*   推奨は `public/music/` に置き /music/ファイル名で参照します。public、Windows パス、src/assets パスは入れません。他の適合ルートパスも使え、/music/ や拡張子で形式を強制しません。
*   [http://、//example.com/file.mp3、data:、blob:、通常相対パスは不可。HTTPS](http://xn--q6j//example.com/file.mp3%E3%80%81data:%E3%80%81blob:%E3%80%81%E9%80%9A%E5%B8%B8%E7%9B%B8%E5%AF%BE%E3%83%91%E3%82%B9%E3%81%AF%E4%B8%8D%E5%8F%AF%E3%80%82HTTPS) 接頭辞は大小文字を区別し、例は小文字です。
*   URL に空白を直接使わず必要ならエンコードします。正しい符号化はファイル存在を保証しません。前後にも空白を加えません。
*   ルートパスには描画時 BASE\_URL を加え、同じサブパスを自分で重ねないでください。HTTPS は維持します。
*   形式通過でもブラウザー対応・アクセスが必要です。共有ページは音声直リンクではありません。外部は fetch で取得するため CORS が必要で、新窓で再生可能でも CORS 許可とは限りません。

保存曲の復元には src を使うため、各曲に別 URL を推奨します。重複は検証禁止ではありませんが最初の一致に戻り、タイトルは識別子ではありません。

## 統合用プレイリスト例

`public/music/my-song.mp3` を自分で用意します。テーマは音声を生成しません。既存 defineThemeConfig({…}) に統合し、import・export・他設定を残して theme を重複させないでください。

```ts
theme: {
  music: {
    enabled: true,
    tracks: [
      {
        title: '私の一曲',
        artist: '著者',
        src: '/music/my-song.mp3',
      },
    ],
  },
},
```

停止だけなら `enabled: false` でリストの消去は不要です。開発は設定の再読込、本番は再ビルド・再配備が必要です。音声のアップロードだけでは tracks に自動追加しません。

## messages.music：19項目の UI とアクセシブル文面

接頭辞は `i18n.locales.<locale>.messages.music.`。任意 **string**、内蔵現在言語と補完を使います。表は簡体中国語／英語の実既定値、例は項目値です。プレーヤー描画と対象状態が条件です。空文字は機能を隠さず、意味あるアクセシブル名を失う場合があります。

| 項目 | 簡体中国語 / 英語既定値 | 役割と制約 | 例 |
| --- | --- | --- | --- |
| `label` | 音乐播放器 / Music player | aside のアクセシブル名。上部 AUDIO CHANNEL ではない。 | `"音楽プレーヤー"` |
| `play` | 播放 / Play | 再生ボタンの名前。表示は PLAY。 | `"再生"` |
| `pause` | 暂停 / Pause | 再生中・ロード中の名前。表示は PAUSE。 | `"一時停止"` |
| `prev` | 上一首 / Previous | 前の曲の名前。表示 PREV。 | `"前の曲"` |
| `next` | 下一首 / Next | 次の曲の名前。表示 NEXT。 | `"次の曲"` |
| `open` | 展开播放器 / Open player | 展開の名前。表示 OPEN。 | `"プレーヤーを開く"` |
| `close` | 收起播放器 / Collapse player | 折畳みの名前。表示 MIN。閉じても停止しない。 | `"プレーヤーを閉じる"` |
| `progress` | 播放进度 / Progress | 進捗スライダーの名前。位置・可動範囲は変えない。 | `"再生位置"` |
| `volume` | 音量 / Volume | 音量スライダーの名前。既定音量は変えず表示 LVL。 | `"音量"` |
| `queue` | 歌单 / Playlist | 一覧展開の名前。QUEUE・SHOW / HIDE は固定。 | `"曲一覧を開く・閉じる"` |
| `mute` | 静音 / Mute | 非ミュート時の名前。表示 MUTE。 | `"ミュート"` |
| `unmute` | 取消静音 / Unmute | 音量0時の復元名。表示 UNMUTE。 | `"ミュート解除"` |
| `idle` | 就绪 / Ready | 初期・曲切替後の SIGNAL 状態。 | `"再生待ち"` |
| `loading` | 加载中 / Loading | 取得・再生待機の SIGNAL 状態。 | `"曲を読み込み中"` |
| `playing` | 播放中 / Playing | 再生時の SIGNAL 状態。 | `"再生中"` |
| `paused` | 已暂停 / Paused | 停止時の SIGNAL 状態。 | `"一時停止中"` |
| `blocked` | 浏览器阻止了自动播放，请点击 PLAY 继续播放。 / Click Play to continue. Your browser blocked automatic playback. | ブラウザー権限拒否の案内。文面で制限は解除できない。 | `"再生ボタンを押してください。"` |
| `error` | 播放失败，请重试或切换歌曲。 / Unable to play. Try again or select another track. | 音声要求・再生失敗とマウント失敗の案内。 | `"曲を読み込めませんでした。再試行してください。"` |
| `noScript` | 请启用 JavaScript 使用播放器。 / Enable JavaScript to use the player. | JavaScript 無効時の noscript。標準 audio 代替 UI は提供しない。 | `"JavaScript を有効にするとプレーヤーを利用できます。"` |

全ターミナル UI の置換表ではありません。PLAY / PAUSE、PREV / NEXT、OPEN / MIN、MUTE / UNMUTE、QUEUE、SHOW / HIDE、TRACKS、LVL、AUDIO CHANNEL、STATE、SIGNAL、STANDBY は固定です。設定はアクセシブル名や SIGNAL の状態文面なので、英語が残っても無効とは限りません。

日本語のロード・エラーだけを上書きする例です。

```ts
i18n: {
  locales: {
    ja: {
      messages: {
        music: {
          loading: '曲を読み込み中',
          error: '曲を読み込めませんでした。再試行してください。',
        },
      },
    },
  },
},
```

言語スイッチと補完は[多言語ガイド](https://demo.anglefeint.com/ja/blog/starter-guide-languages/)へ。文面は言語別、曲は全サイト共通です。

## 音声をいつ取得し、なぜ待つのか

初回で保存した再開状態がなければ、UI 初期化では取得しません。再生、前・次、曲選択で対象を要求し、パネルや一覧を開くだけでは全曲を取得しません。同じタブの再開復元では自動要求する場合があります。

まず曲全体を取得して Blob にし、Audio で再生します。ストリーミングではありません。Range を無視するサーバーでも取得済み内容の位置を変えられます。大容量は初回待ちとメモリーを増やします。自動変換・圧縮・別ビットレート生成はしません。

停止後の再生は音声と Blob を再利用します。別曲では未完取得を中断して旧資源を解放し、戻ると再取得する場合があります。HTTP キャッシュは別層で、全曲の永続キャッシュではありません。不良曲を自動スキップせず再生で再試行できます。再生権限が拒否されると blocked で操作が必要です。

外部は CORS と成功レスポンスが必要です。プロキシ、認証ヘッダー、独自資格情報の設定はありません。同一サイト public は追加 CORS 不要です。文面変更ではパス・権限・形式を直せません。

## 再生、復元、外観の固定動作と範囲

| 項目 | 現在の動作 | site.config 項目か |
| --- | --- | --- |
| 既定曲 | 保存 src が一致しなければ最初の曲。解決済み src で照合。 | いいえ。defaultTrack なし。 |
| 既定音量 | 初回0.5、その後は同タブの保存値を復元可能。 | いいえ。defaultVolume なし。 |
| ミュート | 音量0、解除は記憶した非ゼロ値。取得停止・一時停止ではない。 | いいえ。独立 mute なし。 |
| 次の曲 | 終了で次、最後の次は最初。ランダムでない。 | いいえ。shuffle / repeat / loop なし。 |
| 再開 | sessionStorage に src・位置・音量・折畳み・再開意図を保存し、同タブ移動・復元で試行。ブラウザー権限に従う。 | いいえ。autoplay / resume なし。 |
| 初期パネル | 標準は閉じ、初期引数が保存表示設定より優先。BFCache は別の復元あり。 | いいえ。theme.music.collapsed なし。 |
| 展開・一覧 | UI だけを変え、停止しない。Escape でパネルを閉じる。 | いいえ。キー変更項目なし。 |
| ページ外観 | 現在ページの Matrix / Cyber / Hacker / AI / 基本で、曲の種類ではない。 | いいえ。theme.music.scene なし。 |
| アニメーション | Matrix 固有效果を再生・可視性・折畳みに合わせ、動き軽減設定にも従う。効果失敗は音声を妨げるべきでない。 | いいえ。音楽固有スイッチなし。 |

sessionStorage はセッションで、永続クラウドやタブ間同期ではありません。保存不可でも使えますが復元を保証せず、ページ間の無中断再生も保証しません。JavaScript なしでは noScript を出し、操作できません。

initiallyCollapsed、musicInitiallyCollapsed、scene などのコンポーネント・独自レイアウト引数は公開設定ではなく、theme.music に加えても反映しません。標準は初め閉じ、UI で開けます。曲名もテーマを切り替えません。

設定2項目、曲3項目、文面19項目には使用箇所があり、追加の互換・無効項目は不要です。アクセシブル用途、固定英語、セッションは区別しています。[総合案内](https://demo.anglefeint.com/ja/blog/config-reference/)へ。
