﻿---
title: "Справочник настроек: музыкальный проигрыватель"
description: "Все поля музыки и треков, девятнадцать текстов, загрузка Blob, CORS, ограничения и фиксированное поведение проигрывателя."
url: "https://demo.anglefeint.com/ru/blog/config-music/"
language: "ru"
author: "Anglefeint"
published: "2026-11-13T00:00:00.000Z"
updated: "2026-11-14T00:00:00.000Z"
---

# Справочник настроек: музыкальный проигрыватель

Для первой песни см. [настройку музыки](https://demo.anglefeint.com/ru/blog/starter-guide-3-comments-about-and-theme-toggles/). Файл конфигурации — в [установке](https://demo.anglefeint.com/ru/blog/starter-guide-1-configure-your-site/), остальные модули — в [общем справочнике](https://demo.anglefeint.com/ru/blog/config-reference/).

Проигрыватель настраивается в `theme.music` файла `src/site.config.ts`. Стандартно отключён, плейлист пуст, песен тема не поставляет. Ниже стандарты пакета, не личный плейлист demo.

## theme.music.enabled: переключатель проигрывателя

*   **Тип / стандарт:** boolean / false.
*   **Состояние и действие:** действует. Общий каркас стандартных страниц выводит проигрыватель только при true и хотя бы одном действительном треке.
*   **Ограничения:** одного true без треков недостаточно. При отключении треки не входят в рабочий список и поэлементная проверка пропускается. Настройки/аудиофайлы public не удаляются, прямой доступ к публичным файлам не ограничивается.
*   **Пример:** `theme: { music: { enabled: false } }`.

Общая настройка всех страниц, не отдельных языков/главной. Стандартные страницы каркаса делят плейлист, музыка не ограничена главной. Подключение каркаса собственной страницей определяется самой страницей.

## theme.music.tracks: список треков

*   **Тип / стандарт:** MusicTrack\[\] / \[\]. Три поля элемента ниже.
*   **Состояние и действие:** условно при включённой музыке. Порядок массива задаёт список и переключение; публичного максимума нет.
*   **Ограничения:** при включении нужен массив. Пустой допустим, но эффективный проигрыватель выключен. Массив заменяется целиком, не объединяется со старым/стандартным. Добавляя песни, сохраните нужные элементы.
*   **Пример:** \[{ title: ‘Моя песня’, artist: ‘Автор’, src: ‘`/music/my-song.mp3`’ }\].

Названия, авторы и адреса находятся в общем массиве, не i18n. Смена языка не меняет плейлист автоматически. Объект плейлиста сторонней платформы или sharing-ссылка этому массиву не соответствуют.

### Поля каждого трека

Полный префикс `theme.music.tracks[]`. «Нет» означает отсутствие автоматически подставляемого значения.

| Поле | Тип / стандарт | Состояние, действие и ограничения | Пример |
| --- | --- | --- | --- |
| title | string, обязателен / нет | Условно: имя в главном блоке, свёрнутом заголовке и списке. Непустая строка после trim; пустота вызывает ошибку, имя файла/метаданные не используются | ‘Моя песня’ |
| artist | string, необязателен / отсутствует, нормализуется в ‘’ | Условно: автор в главном блоке и списке. Если указан, string с trim. Пустое не дополняется автором сайта/аудиометаданными | ‘Автор’ |
| src | string, обязателен / нет | Условно: источник, начинается с одного / или строчного https://, без пробелов/обратных слешей. HTTPS должен разбираться URL; существование/аудиосодержимое не проверяется | ‘/music/my-song.mp3’ |

Название и автор — текст без Markdown/HTML. Публичных полей обложки, текста песни, длительности, альбома, отдельного ID или громкости трека нет.

Ограничения src:

*   Локальное аудио рекомендуется в `public/music/` с /music/именем без public, диска Windows или src/assets. Другие соответствующие корневые пути допустимы; /music/ и расширение не принудительны.
*   Не принимаются http://, //example.com/file.mp3, data:, blob: и обычные относительные пути. HTTPS-префикс регистрозависим, используйте строчный https://.
*   Адрес без прямых пробелов; при необходимости URL-кодируйте путь, но корректное кодирование не гарантирует наличие файла. Не добавляйте пробелы по краям.
*   Корневые пути получают Astro BASE\_URL при рендеринге; не дублируйте префикс подпути вручную. HTTPS не меняется.
*   Формат подтверждает лишь конфигурацию. Нужны доступный файл и поддержка браузера; страница платформы не прямой звук. Fetch внешнего источника требует CORS для сайта; воспроизведение в новой вкладке этого не доказывает.

Для восстановления сохранённого трека используется src: рекомендуются разные адреса. Повторы не запрещены проверкой, но восстановление выберет первый. Заголовок не идентификатор восстановления.

## Пример плейлиста для объединения

Сначала подготовьте `public/music/my-song.mp3`. Тема не создаёт аудиофайл по пути примера. Объедините с существующим `defineThemeConfig({...})` в `src/site.config.ts`, сохранив import/export/личные настройки без второго theme.

```ts
theme: {
  music: {
    enabled: true,
    tracks: [
      {
        title: 'Моя песня',
        artist: 'Автор',
        src: '/music/my-song.mp3',
      },
    ],
  },
},
```

Для отключения достаточно `enabled: false`, очищать список не нужно. Dev должен перечитать конфигурацию, онлайн-сайту нужны сборка/размещение. Загрузка аудио без tracks не добавляет его автоматически.

## messages.music: девятнадцать текстов интерфейса и доступности

Префикс `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 | Доступное имя восстановления при нуле, видимый 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. | noscript без JavaScript; нативный запасной аудиоконтрол не предоставляется | `"Включите JavaScript, чтобы использовать плеер."` |

Это не полный перевод видимого терминального UI. PLAY/PAUSE, PREV/NEXT, OPEN/MIN, MUTE/UNMUTE, QUEUE, SHOW/HIDE, TRACKS, LVL, AUDIO CHANNEL, STATE, SIGNAL и STANDBY фиксированы реализацией. Настраиваемые поля — доступные имена или видимые статусы SIGNAL; английская кнопка не означает неработающее поле.

Например, переопределение русских сообщений загрузки/ошибки:

```ts
i18n: {
  locales: {
    ru: {
      messages: {
        music: {
          loading: 'Загрузка трека',
          error: 'Не удалось загрузить трек; попробуйте снова.',
        },
      },
    },
  },
},
```

Включение и откат языков — в [языковом руководстве](https://demo.anglefeint.com/ru/blog/starter-guide-languages/). Тексты следуют языку, треки общие.

## Когда скачивается аудио и почему приходится ждать?

При первом использовании без сохранённого продолжения инициализация не скачивает звук. Запрос выбранного трека возникает после play, предыдущего, следующего или выбора песни. Раскрытие панели/списка не скачивает весь плейлист. Восстановление сессии вкладки может автоматически запросить выбранный трек.

Сейчас выбранное аудио скачивается целиком, преобразуется в Blob и передаётся Audio. Это не потоковое воспроизведение с первых байтов. Даже при игнорировании Range сервером загруженное можно перематывать. Большие файлы увеличивают ожидание/память, тема не перекодирует, не сжимает и не создаёт битрейты автоматически.

Продолжение после паузы использует текущее аудио и Blob. Смена трека прерывает незавершённую загрузку и освобождает старый ресурс; возврат может запросить заново. HTTP-кэш сервера/браузера — отдельный слой, не постоянный кэш всех песен проигрывателя. Плохой трек автоматически не пропускается; повторите play. При запрете воспроизведения показывается blocked и нужно действие пользователя.

Внешний источник должен разрешать CORS и возвращать успех. Настроек прокси, заголовков авторизации или собственных credentials нет. Public-аудио того же сайта не требует CORS. Текст подсказки не исправляет путь, разрешения или формат.

## Воспроизведение, продолжение и вид: фиксированное поведение

| Пункт | Реальное поведение | Поле site.config? |
| --- | --- | --- |
| Начальный трек | Первый при отсутствии совпадающего сохранённого; совпадение по разрешённому src | Нет defaultTrack |
| Начальная громкость | 0.5 при первом старте, затем возможна сохранённая вкладкой | Нет defaultVolume |
| Без звука | Громкость 0, восстановление запомненного ненулевого; не останавливает загрузку/воспроизведение | Нет отдельного mute |
| Следующая песня | По порядку, после последней первая, не случайно | Нет shuffle/repeat/loop |
| Продолжение | sessionStorage сохраняет адрес, позицию, громкость, сворачивание и намерение продолжить; навигация/восстановление вкладки пытаются продолжить с учётом разрешений браузера | Нет autoplay/resume |
| Начальная панель | Стандартно свёрнута; начальные параметры компонента приоритетнее сохранённого вида, BFCache имеет отдельное восстановление | Нет theme.music.collapsed |
| Сворачивание/список | Только вид, не пауза; Escape сворачивает панель | Нет поля горячих клавиш |
| Стиль страницы | Каркас выбирает Matrix/Cyber/Hacker/AI или базовый по странице, не жанру песни | Нет theme.music.scene |
| Анимация | Matrix учитывает воспроизведение, видимость страницы, сворачивание и Reduced Motion; сбой эффекта не должен блокировать звук | Нет отдельного переключателя эффектов музыки |

sessionStorage — состояние сессии, не постоянная облачная запись или синхронизация вкладок. При ограничении сохранения проигрыватель работает без гарантии восстановления. Бесшовность/непрерывность между страницами не гарантируется. Без JavaScript показывается noScript, взаимодействие недоступно.

`initiallyCollapsed`, `musicInitiallyCollapsed`, `scene` компонентов/собственных макетов — не публичные site.config-поля, добавление в `theme.music` не работает. Стандартная страница начинает свёрнутой, пользователь раскрывает её. Треки/названия не переключают атмосферу автоматически.

Два поля музыки, три поля трека и девятнадцать текстов потребляются; дополнительных совместимых/неработающих полей нет. Доступность, фиксированный английский и сессионное состояние различены выше. [Назад к общему справочнику](https://demo.anglefeint.com/ru/blog/config-reference/).
