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

$ опубликовано 2026-11-13 | | обновлено 2026-11-14
Контекст: Все поля музыки и треков, девятнадцать текстов, загрузка Blob, CORS, ограничения и фиксированное поведение проигрывателя.

Плейлист, источники аудио, интерфейс и продолжение сессии.


Вывод
слов 1.4k токенов 1.9k

Для первой песни см. настройку музыки. Файл конфигурации — в установке, остальные модули — в общем справочнике.

Проигрыватель настраивается в 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 не работает. Стандартная страница начинает свёрнутой, пользователь раскрывает её. Треки/названия не переключают атмосферу автоматически.

Два поля музыки, три поля трека и девятнадцать текстов потребляются; дополнительных совместимых/неработающих полей нет. Доступность, фиксированный английский и сессионное состояние различены выше. Назад к общему справочнику.