Справочник настроек: музыкальный проигрыватель
Плейлист, источники аудио, интерфейс и продолжение сессии.
На этой странице
Для первой песни см. настройку музыки. Файл конфигурации — в установке, остальные модули — в общем справочнике.
Проигрыватель настраивается в 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.
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; английская кнопка не означает неработающее поле.
Например, переопределение русских сообщений загрузки/ошибки:
i18n: {
locales: {
ru: {
messages: {
music: {
loading: 'Загрузка трека',
error: 'Не удалось загрузить трек; попробуйте снова.',
},
},
},
},
},
Включение и откат языков — в языковом руководстве. Тексты следуют языку, треки общие.
Когда скачивается аудио и почему приходится ждать?
При первом использовании без сохранённого продолжения инициализация не скачивает звук. Запрос выбранного трека возникает после 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 не работает. Стандартная страница начинает свёрнутой, пользователь раскрывает её. Треки/названия не переключают атмосферу автоматически.
Два поля музыки, три поля трека и девятнадцать текстов потребляются; дополнительных совместимых/неработающих полей нет. Доступность, фиксированный английский и сессионное состояние различены выше. Назад к общему справочнику.