WaveSurfer.js: аудиоплеер, звуковая волна и 8 живых примеров
Восемь связанных примеров настоящего аудиоплеера: звуковая волна, фрагменты, повтор, масштаб и заметки. Три авторских записи, исходники и запуск Windows/Linux.

WaveSurfer.js: превратить аудио в рабочий интерфейс
Обычный аудиофайл можно запустить стандартным плеером, но в рабочем кабинете часто требуется больше. Оператору нужно найти конкретный момент разговора, преподавателю — повторить короткую фразу, редактору — оставить замечание к отрезку, а разработчику — связать эти действия с карточкой документа. Когда человек видит только кнопку запуска и общую длительность, для каждой задачи ему приходится прослушивать запись заново.
WaveSurfer.js помогает построить интерфейс вокруг звуковой волны: показать положение воспроизведения, перейти к секунде, увеличить нужную область и разместить подписанные фрагменты. Ниже находится полноценная аудиомастерская с восемью связанными примерами. Это настоящая библиотека, три собственные демонстрационные записи, работающие элементы управления и исходники, которые можно скачать и изменить.
Начните с короткого прослушивания, затем отметьте отрезок и выгрузите его описание в JSON. Так станет понятно, какая часть решается плеером, что нужно хранить в своём приложении и где потребуется отдельная серверная логика. Цель материала — довести знакомство до понятной операции, которую можно перенести в реальный сервис.
Где применять: поддержка, обучение, редактура и каталог
В службе поддержки звуковая волна помогает быстро перейти от карточки обращения к нужному месту записи. Подпись вроде «уточнение адреса» полезнее абстрактной секунды: другой сотрудник понимает, зачем открывать фрагмент. Ссылка на аудио, границы и заметка могут быть частью внутреннего комментария. При этом право доступа к записи проверяет сервер, а плеер отвечает за удобное прослушивание.
В обучении востребованы замедление, повтор небольшого отрезка и переход к заранее выбранным упражнениям. Редактору подкаста удобно собрать замечания без пересылки нескольких обрезанных копий. В каталоге звуков дизайнер может сравнивать короткие образцы, не открывая внешнюю программу для каждого файла. Внутренний кабинет исследования может связывать аудиофрагменты с карточками наблюдений.
Перед внедрением сформулируйте одну законченную задачу пользователя. Например: найти фразу, подписать её, передать замечание коллеге и затем открыть этот же момент. Такое описание сразу выявляет необходимые поля, права и состояния интерфейса. Сам по себе красивый график ещё не объясняет человеку, что с ним делать; поэтому в мастерской каждый экран начинается с действия и ожидаемого результата.
Что делает библиотека, а что остаётся приложению
WaveSurfer рисует форму сигнала и управляет воспроизведением. Regions добавляет визуальные отрезки, Timeline — временную шкалу. В нашем проекте Bootstrap оформляет формы и кнопки, а собственный JavaScript связывает выбор записи, подписи и экспорт. Эти роли отделены: можно изменить оформление или формат хранения, сохранив работу самого плеера.
Выделение региона не вырезает WAV. Скачивание JSON не создаёт новый аудиофайл, а увеличение волны не улучшает качество записи. Распознавание речи, шумоподавление, монтаж и кодирование результата требуют других инструментов. В этой мастерской таких действий нет, и интерфейс прямо говорит, что сохраняются только границы и подписи.
Если задача ограничивается обычным прослушиванием без разметки, стандартный audio с controls может оказаться достаточным. Если нужны рабочие фрагменты и своя навигация, удобно использовать WaveSurfer. Для состояния вокруг интерфейса во Vue можно дополнительно изучить практические приёмы VueUse: черновики, видимость и управление загрузкой. Не стоит смешивать выбор библиотеки с требованием переписать весь продукт.
Версия 8.1.0, зависимости и воспроизводимая установка
Мастерская закрепляет WaveSurfer.js 8.1.0 и Bootstrap 5.3.9. На момент подготовки npm latest для WaveSurfer указывал на 8.1.0. Установленные пакеты и транзитивные зависимости записаны в package-lock.json. Для сборки и тестов проекта используется Node 24; готовая страница работает как обычный HTML, CSS и JavaScript.
В ветке 8 есть реактивное состояние getState; мы используем его для подписи стадии загрузки. Основные команды плеера и события читаются рядом в src/app.mjs. При переносе примеров не смешивайте файл библиотеки одной версии с плагином другой: Regions и Timeline в нашей поставке берутся из того же установленного пакета.
Авторский код и синтезированное аудио доступны по MIT. WaveSurfer распространяется по BSD-3-Clause, Bootstrap — по MIT; тексты лицензий включены в архив. Для сверки используйте выпуск 8.1.0 и официальную документацию. Команда npm ci повторяет закреплённый набор. После обновления зависимостей нужны новые проверки поведения, а не только успешная установка.
Фрагмент файла package.json
{"name":"aen-wavesurfer-workshop","version":"1.0.0","private":true,"type":"module","license":"MIT","engines":{"node":">=24"},"scripts":{"build":"node tools/build.mjs","test":"node --test tests/*.test.mjs","start":"node tools/serve.mjs"},"dependencies":{"bootstrap":"5.3.9","wavesurfer.js":"8.1.0"}}
Мини-мастерская: восемь задач одного аудиоплеера
Выберите пример в списке, прочитайте короткое задание и поработайте с плеером ниже. Первый экран показывает запуск, паузу и отказ загрузки. Затем можно перейти к секунде, настроить темп, отметить регион, включить повтор, увеличить волну, сменить запись и сохранить заметки. Все восемь экранов используют один экземпляр плеера: положение и настройки не обнуляются только из-за смены учебной задачи.
В библиотеке три авторских WAV длительностью 12, 16 и 10 секунд. Они синтезированы скриптом проекта: мягкий мотив, короткий ритм и группы сигналов с тишиной. Это даёт разные формы волны и позволяет воспроизводить опыт без чужих записей разговоров. Звук включается только явной кнопкой, начальная громкость плеера равна 25 процентам.
При смене записи её регионы остаются в памяти вкладки и восстанавливаются при возврате. После закрытия страницы память исчезает, поэтому важную разметку скачивайте в JSON. Свой файл можно выбрать локально; он не отправляется на сервер. Для долгой работы удобнее открыть мастерскую отдельно, а реальные файлы проекта доступны в просмотрщике исходников внизу.
Быстрый запуск в Windows и PowerShell
Распакуйте проект в отдельный каталог и откройте там PowerShell. Проверьте Node, установите зависимости из lock-файла, соберите public и выполните тесты. Затем npm start запускает небольшой сервер на 127.0.0.1:8551. Откройте этот адрес в браузере; для остановки нажмите Ctrl+C в той же консоли.
В архиве уже есть готовая папка public. Если нужно только посмотреть работу, npm start использует стандартные модули Node и не требует предварительной установки пакетов. При установленном PHP можно раздать ту же папку встроенным сервером. Это полезно разработчику PHP-сайта: для просмотра готовой браузерной части не нужно запускать отдельный фреймворк.
Не открывайте index.html двойным щелчком вместо HTTP-сервера. Модули JavaScript и загрузка JSON должны получать ресурсы по корректным адресам. Если порт занят, выберите другой в tools/serve.mjs либо команде PHP; останавливать неизвестные процессы ради примера не требуется. Сервер разработки привязан к loopback и не предназначен для обслуживания публичного домена.
Фрагмент файла README.md
node --version
npm ci --ignore-scripts
npm run build
npm test
npm start
Фрагмент файла README.md
php -S 127.0.0.1:8551 -t public
Linux: тот же проект и отдельные зависимости
На Linux порядок действий такой же: установить Node 24, перейти в каталог, выполнить npm ci, build и test. Не переносите node_modules с Windows. Хотя наш сборщик в основном копирует файлы, привычка устанавливать зависимости заново сохраняет воспроизводимость и не привязывает будущие изменения к случайному локальному окружению.
В архив включён tools/run-linux-check.sh. Он копирует исходники из read-only входного каталога, устанавливает пакеты внутри отдельной среды, собирает мастерскую и сохраняет результаты. Скрипт не требует изменения системных файлов проекта. Docker является одним из способов такого повторения, но для обычного Linux-запуска мастерской контейнер не обязателен.
Для CI закрепляйте также образ по digest и сохраняйте версию Node рядом с отчётом. Установка зависимости, успешный Node-тест и фактическая проверка браузера отвечают на разные вопросы. Даже одинаковые файлы public не доказывают работу конкретного мобильного кодека или настройку публичного сервера. Поэтому инструкции запуска и фактически выполненная приёмка описываются отдельно.
Фрагмент файла README.md
cd wavesurfer-project
node --version
npm ci --ignore-scripts
npm run build
npm test
npm start
Фрагмент файла tools/run-linux-check.sh
#!/bin/sh
set -eu
mkdir -p /project /qa
tar -C /input --exclude=node_modules --exclude=public -cf - . | tar -C /project -xf -
cd /project
node --version > /qa/node.txt
npm ci --ignore-scripts --no-audit --no-fund > /qa/install.log 2>&1
npm run build > /qa/build.log 2>&1
npm test > /qa/tests.log 2>&1
node tools/source-hashes.mjs > /qa/source-hashes.json
cp public/build-info.json /qa/build-info.json
cat /qa/tests.log
Создание WaveSurfer и подключение Regions и Timeline
В src/app.mjs создаётся один WaveSurfer с контейнером waveform, цветами волны, курсором и включённым переходом перетаскиванием. Timeline добавляется сразу в plugins. Regions регистрируется через registerPlugin, и приложение сохраняет ссылку на него для добавления, выбора и удаления фрагментов.
Библиотеки поставляются локально в public/vendor. Это позволяет открыть опубликованную страницу без дополнительной CDN-зависимости. Сборщик берёт именно ESM-файлы установленной версии и кладёт их рядом с приложением. Никакой скрытой сборки при первом посещении сайта не происходит: сервер выдаёт уже подготовленные файлы.
Экземпляр плеера должен соответствовать жизненному циклу интерфейса. Если компонент удаляется из SPA, его нужно уничтожить, чтобы не оставить подписки и ресурсы. В нашем отдельном документе при уходе со страницы воспроизведение ставится на паузу, а перед окончательной выгрузкой вызывается destroy. При встраивании во Vue или React аналогичный cleanup размещается в событии размонтирования.
Фрагмент файла src/app.mjs
const wave = WaveSurfer.create({
container: '#waveform', height: 142, waveColor: '#70a79a', progressColor: '#0b675a',
cursorColor: '#bd8f18', cursorWidth: 2, barWidth: 2, barGap: 2,
normalize: false, dragToSeek: true, autoScroll: true, autoCenter: true,
plugins: [Timeline.create({ height: 24, style: { color: '#244e44', fontSize: '11px' } })],
});
const regions = wave.registerPlugin(Regions.create());
Пример 1. Слушать, поставить паузу и увидеть состояние
Нажмите «Слушать»: название кнопки сменится на «Пауза», время начнёт двигаться, а пройденная часть волны изменит цвет. Повторное нажатие останавливает воспроизведение, сохраняя позицию. Кнопка «В начало» одновременно ставит паузу и возвращает курсор к нулю. Эти действия различаются и названы по результату.
Кнопки управления недоступны, пока аудио не подготовлено. Подпись стадии загрузки берётся из настоящего состояния WaveSurfer, а длительность — из загруженной записи. Движение времени не рисуется отдельным демонстрационным таймером: обработчик timeupdate читает положение реального аудиоплеера.
Запуск может быть отклонён браузером, поэтому Promise метода play обрабатывается. Интерфейс не сообщает об успехе заранее. При отказе пользователь получает понятное сообщение и возможность повторить действие. На практике это особенно важно внутри iframe, в мобильном браузере и после асинхронного действия, потерявшего связь с пользовательским нажатием. О базовом механизме можно прочитать в описании HTMLMediaElement.play.
Фрагмент файла src/app.mjs
async function togglePlayback() {
if(!ready) return;
if(wave.isPlaying()) {wave.pause();cancelSegment();return;}
cancelSegment();
try { await wave.play(); } catch(error) { fail(new Error(`Браузер не запустил звук: ${error.message}. Нажмите «Слушать» ещё раз.`)); }
}
Ошибка загрузки и восстановление без перезагрузки страницы
На первом экране есть кнопка испытания ошибки. Она обращается к отсутствующему учебному WAV на том же сайте. Плеер перестаёт считаться готовым, показывает сообщение и предлагает повторить загрузку выбранной записи. Нажмите повторение: обычный файл снова декодируется, и управление возвращается в рабочее состояние.
Каждому запуску загрузки присваивается номер поколения. Если человек быстро выбирает другую запись, позднее завершение предыдущей операции не должно перезаписать актуальный заголовок и состояние. Ошибка отменённой загрузки также не превращается в сообщение о поломке новой записи. Такой подход пригодится любому интерфейсу с переключением файлов.
Различайте отсутствие файла, проблему сети, неподдерживаемый кодек и запрет запуска звука. Для пользователя полезно сохранить возможность выбрать другой файл и не терять весь интерфейс. Для разработчика полезны точный URL, HTTP-код и сообщение декодирования. В production не выводите чувствительные внутренние пути, но оставляйте диагностическую информацию в подходящем журнале.
Фрагмент файла src/app.mjs
async function loadTrack(track, broken=false) {
saveMemory(); const own=++generation; current=track; wave.pause(); cancelSegment(); controls(false); regions.clearRegions(); active=null;
$('error').hidden=true; $('retry').hidden=true; $('track-title').textContent=track.title;
$('track-description').textContent=track.description || 'Ваш локальный файл; содержимое не отправляется на сервер.';
$('zoom').value='0'; $('zoom-value').textContent='Вся запись'; wave.setOptions({minPxPerSec:0}); $('loop').checked=false;
$('loop-status').textContent='Повтор выключен.'; setStatus('Загружаем и декодируем аудио…'); renderRegionList();
try {
if (broken) await wave.load('./audio/missing-training-file.wav');
else if (track.file) await wave.loadBlob(track.file);
else await wave.load(track.url);
if (own!==generation) return;
controls(true); $('seek').max=String(wave.getDuration()); $('jump-time').max=String(wave.getDuration());
const saved=memory.get(track.id) || [{id:'intro',start:1,end:Math.min(3.5,wave.getDuration()),label:'Первый фрагмент'}];
for (const item of saved) if(item.end<=wave.getDuration()) addRegion(item);
active=regions.getRegions()[0] || null; if(active) chooseRegion(active.id); else renderRegionList();
renderTime(); renderAudioSettings(); setStatus(`Готово: ${track.title}. Нажмите «Слушать», чтобы включить звук.`);
} catch(error) {
if(own!==generation || error?.name==='AbortError') return;
controls(false); fail(error);
}
}
Пример 2. Переход по волне, секунде и клавиатуре
Клик по волне выбирает положение, но сам по себе не включает звук. На втором экране можно ввести точную секунду и нажать «Перейти без запуска звука». Ползунок под волной дублирует переход; он доступен с клавиатуры, поэтому мышь и касание не становятся единственным способом работы.
Числовая позиция ограничивается от нуля до длительности. Значение за концом записи не должно создавать отрицательный прогресс или непонятную ошибку. Кнопки минус и плюс две секунды используют то же правило. Состояние отображается в формате минут и секунд с десятыми, а данные продолжают храниться числом секунд.
Для своего сервиса можно добавить ссылку с параметром момента, например открыть карточку и затем вызвать setTime после готовности аудио. Проверяйте число на серверной или клиентской границе, а не доверяйте строке URL. Ссылка должна указывать также на неизменяемую версию записи: после замены аудиофайла прежняя секунда может означать другой фрагмент.
Фрагмент файла src/model.mjs
export function clamp(value, min, max) {
const n = Number(value);
return Number.isFinite(n) ? Math.min(max, Math.max(min, n)) : min;
}
Фрагмент файла src/model.mjs
export function formatTime(value) {
const n = Math.round(Math.max(0, Number(value) || 0) * 10) / 10;
return `${Math.floor(n / 60)}:${(n % 60).toFixed(1).padStart(4, '0')}`;
}
Пример 3. Скорость, громкость и режим без звука
На третьем экране можно выбрать скорость от 0,75 до 2, изменить громкость и включить режим без звука. Настройки применяются к тому же плееру, поэтому их удобно сравнивать во время воспроизведения. Подпись под элементами управления показывает фактические значения, прочитанные обратно через API.
В setPlaybackRate передаётся preservePitch=true: намерение интерфейса — менять темп без специального эффекта изменения высоты. Результат зависит от браузерного медиадвижка и самого звука. Для коротких синтетических дорожек легко увидеть ускорение счётчика; для речевого продукта обязательно проверяйте разборчивость на реальных разрешённых образцах.
Громкость программы и громкость устройства не равны. На некоторых мобильных системах уровень регулируется системными кнопками, и значение JavaScript не гарантирует определённую слышимую громкость. Поэтому мы начинаем с умеренного уровня и не запускаем звук автоматически. Режим mute оставляет скорость и позицию: пользователь может выключить звук, не разрушая остальную настройку.
Фрагмент файла src/app.mjs
$('rate').addEventListener('change',()=>{wave.setPlaybackRate(Number($('rate').value),true);renderAudioSettings();});
$('volume').addEventListener('input',()=>{wave.setVolume(Number($('volume').value)/100);renderAudioSettings();});
$('mute').addEventListener('change',()=>{wave.setMuted($('mute').checked);renderAudioSettings();});
Пример 4. Создание регионов с понятными подписями
Введите начало, конец и подпись, затем добавьте фрагмент. Он появится на волне и в списке ниже. Кнопка «Выбрать» заполняет форму для изменения, «К началу» переводит курсор, а «Удалить» убирает только отметку. Сам аудиофайл при этих действиях остаётся прежним.
Для мыши доступны перетаскивание и изменение границ на волне. Для точности и мобильного использования предусмотрены обычные числовые поля. Это важное дополнение: маленькая ручка региона не должна быть единственным способом установить конец отрезка. В мастерской минимальная длина составляет 0,1 секунды, максимальное число регионов — двадцать.
Подпись вставляется в созданный элемент через textContent. Поэтому текст с угловыми скобками остаётся текстом, а не превращается в HTML. При переносе в систему с пользовательскими комментариями сохраняйте это свойство. Разрешение произвольного HTML требует отдельного обоснования и обработки; обычному названию аудиофрагмента оно чаще всего не нужно.
Фрагмент файла src/model.mjs
export function validateRegion(start, end, duration, label) {
const a = Number(start), b = Number(end), text = String(label).trim();
if (!Number.isFinite(a) || !Number.isFinite(b) || a < 0 || b > duration || b - a < 0.1)
throw new Error('Начало и конец должны быть внутри записи; длина — не меньше 0,1 секунды.');
if (!text || text.length > 120) throw new Error('Напишите подпись от 1 до 120 символов.');
return { start: Math.round(a * 1000) / 1000, end: Math.round(b * 1000) / 1000, label: text };
}
Фрагмент файла src/app.mjs
function addRegion(data) {
return regions.addRegion({ ...data, content:regionLabel(data.label), color:'rgba(194,199,105,0.27)', drag:true, resize:true, minLength:0.1 });
}
Идентификатор, границы и версия аудиозаписи
Региону нужен стабильный идентификатор, чтобы отличать изменение существующей заметки от добавления новой. В этой локальной мастерской он создаётся из времени и счётчика. Для совместной серверной работы следует использовать выбранный в приложении формат ID и согласованный протокол обновлений; локальная строка не решает конфликты нескольких пользователей.
Границы хранятся в секундах, подпись — строкой. При экспорте также добавляются идентификатор записи, длительность и версия схемы. Это минимальный контракт, который позволяет отклонить случайный импорт заметок от другой демонстрационной дорожки. Для реального хранилища лучше связывать разметку с версией объекта или хешем аудио, а не только именем файла.
В приложении могут быть дополнительные поля: автор, дата, статус обсуждения и тип отметки. Добавляйте их осознанно вместе с проверкой и отображением. Не полагайтесь на свободный JSON как на готовый контракт базы. Если впоследствии нужна история изменений, храните ревизию и проверяйте её при сохранении, чтобы поздний ответ не затёр чужую работу.
Фрагмент файла src/model.mjs
export function notesDocument(track, duration, regions) {
return { schema: 1, track, duration, regions: regions.map(({ id, start, end, label }) => ({ id, start, end, label })) };
}
Пример 5. Повтор выбранного фрагмента
Выберите регион в пятом примере, включите повтор и нажмите «Слушать фрагмент». Воспроизведение начнётся с его начала. Когда текущая позиция достигнет конца, приложение либо вернётся к началу, либо остановится — в зависимости от флажка. Подпись показывает число завершённых проходов, а обычная кнопка паузы прекращает цикл.
Такой режим удобен для обучения, проверки короткой инструкции и повторного прослушивания спорного места. Пользователь не должен каждый раз искать начало мышью. При смене выбранного региона воспроизведение ставится на паузу: новый выбор не начинает звучать неожиданно. При ручном переходе по ползунку режим сегмента отменяется.
Повтор здесь основан на событиях плеера и не обещает точность до аудиосэмпла. Это интерфейсный инструмент, а не музыкальный секвенсор. Для бесшовного музыкального цикла, точного монтажа или обработки сигнала потребуется другой уровень работы с Web Audio либо серверным аудиопроцессором. Подпись региона и временные границы при этом можно использовать как исходные данные.
Фрагмент файла src/app.mjs
async function playSegment() {
if(!ready || !active) return;
playingSegment=true; loopCount=0;
try {await wave.play(active.start); $('loop-status').textContent=$('loop').checked?'Повтор включён. Нажмите «Пауза», чтобы остановить.':'Фрагмент проиграется один раз.';}
catch(error) {playingSegment=false;fail(error);}
}
Фрагмент файла src/app.mjs
wave.on('timeupdate',(time)=>{
if(playingSegment && active && time>=active.end) {
if($('loop').checked) {loopCount++;wave.setTime(active.start);$('loop-status').textContent=`Повтор включён. Завершено проходов: ${loopCount}.`;}
else {playingSegment=false;wave.pause();wave.setTime(active.end);$('loop-status').textContent='Фрагмент прослушан.';}
}
renderTime();
});
Пример 6. Масштаб и временная шкала
На шестом экране увеличьте число пикселей на секунду. Волна станет шире доступной области, и появится внутренняя горизонтальная прокрутка. При этом сама страница не должна расширяться за экран телефона. Кнопка «Показать запись целиком» возвращает исходный масштаб и позволяет снова оценить всю структуру.
Timeline рисует отметки времени, связанные с аудио. Он помогает сопоставить форму сигнала с числом секунд и не спутать увеличение картинки с изменением длительности. Масштабирование полезно для выбора границ, но не создаёт более подробный исходный сигнал: точность зависит от загруженного аудио и способа представления волны.
Проверяйте узкий iframe отдельно от широкого окна. Даже на большом мониторе встроенный плеер может находиться в маленькой колонке. В нашей верстке контейнер имеет ограниченную ширину, панели перестраиваются, а длинный код прокручивается внутри собственного блока. Это позволяет совмещать мастерскую с боковой навигацией статьи, не ломая её общий макет.
Фрагмент файла src/app.mjs
$('zoom').addEventListener('input',()=>{const n=Number($('zoom').value);wave.zoom(n);$('zoom-value').textContent=n?String(n):'Вся запись';});
$('zoom-reset').addEventListener('click',()=>{wave.zoom(0);$('zoom').value='0';$('zoom-value').textContent='Вся запись';});
Пример 7. Библиотека и выбор своего файла
Седьмой экран содержит три записи с разной формой сигнала. Смена производится отдельной кнопкой: выбор пункта списка ещё не прерывает текущее прослушивание. После открытия другой дорожки плеер ставится на паузу, готовит новую волну и показывает её название. Разметка предыдущей дорожки сохраняется в памяти до закрытия вкладки.
Ниже можно выбрать свой небольшой аудиофайл. Ограничение мастерской — восемь МиБ. Сначала проверяются размер и ожидаемый тип, затем loadBlob передаёт выбранный Blob библиотеке. Проверка расширения или MIME не гарантирует успешное декодирование: фактическую пригодность определяет браузер, и ошибка остаётся частью обычного сценария восстановления.
Выбор локального файла не равен загрузке на сервер. Здесь нет POST с аудио, файлового хранилища или автоматического чтения соседних каталогов. Для реальной системы загрузки потребуется отдельный обработчик, ограничения, проверка формата и права. Пользователю стоит прямо сообщать, где находится файл и что произойдёт при закрытии страницы; это предотвращает ложное ожидание сохранения.
Фрагмент файла src/model.mjs
export function validateAudioFile(file) {
if (!file || !Number.isFinite(file.size) || file.size <= 0 || file.size > 8 * 1024 * 1024)
throw new Error('Выберите непустой аудиофайл до 8 МиБ.');
if (!/^audio\//.test(file.type) && !/\.(wav|mp3|ogg|m4a|flac)$/i.test(file.name))
throw new Error('Ожидается аудиофайл WAV, MP3, OGG, M4A или FLAC.');
return `local-${file.name}-${file.size}-${file.lastModified || 0}`;
}
Собственные WAV: почему в примере нет чужих разговоров
Все три демонстрационные дорожки создаёт tools/audio.mjs. Генератор пишет моно PCM WAV с частотой 22050 Гц и разрядностью 16 бит. Мягкая огибающая уменьшает резкие скачки на границах тонов; уровни выбраны с запасом до насыщения. Проверка читает полученные сэмплы и подтверждает длительность, наличие сигнала и отсутствие клиппинга.
Такие файлы не изображают настоящую речь. Их задача — дать воспроизводимый материал, на котором хорошо видны импульсы, паузы и разные участки. Можно свободно менять частоты и огибающие, пересобирать public и наблюдать, как изменяется волна. Для демонстрации собственного продукта выбирайте материал, на использование которого у вас есть права.
Синтетическое аудио также облегчает техническую проверку: известна точная длительность, формат и ожидаемый диапазон значений. Оно не заменяет оценку UX на длинной речи, стерео или сжатом VBR-файле. Если ваш сервис работает с часовыми интервью, дополнительно проверяйте память, задержку открытия и удобство перемещения именно на таком материале.
Фрагмент файла tools/audio.mjs
export const tracks = [
{id:'morning',title:'Утренний мотив · 12 секунд',duration:12,description:'Мягкая последовательность нот с паузами: видно, где начинается и заканчивается каждая фраза.',url:'./audio/morning.wav'},
{id:'rhythm',title:'Ритм мастерской · 16 секунд',duration:16,description:'Короткие щелчки и низкие тоны: удобно проверять переход, масштаб и повтор фрагмента.',url:'./audio/rhythm.wav'},
{id:'signals',title:'Сигналы и тишина · 10 секунд',duration:10,description:'Три группы синтетических сигналов с разной огибающей и тихими промежутками.',url:'./audio/signals.wav'},
];
Пример 8. Экспорт и обратный импорт JSON
В восьмом примере скачайте заметки. JSON содержит схему, идентификатор текущей дорожки, её длительность и массив регионов. Для удобства тот же текст появляется в поле импорта: можно посмотреть структуру, удалить один регион и затем вернуть экспортированную разметку. Кнопка копирования сообщает успех только после подтверждения браузерного Clipboard API.
Импорт сначала полностью проверяет документ и только затем заменяет существующие регионы. Неверная запись, несовместимая длительность, повторяющиеся ID, неправильные типы или границы отклоняются без частичного применения. Это важнее красивой формы ошибки: пользователь должен сохранить прежнюю разметку, если загруженный документ оказался испорчен.
Наш контракт ограничивает JSON тридцатью двумя тысячами символов и двадцатью регионами. Это учебные ограничения конкретного интерфейса. В серверном API необходимо повторять проверки на доверенной стороне и применять собственные лимиты запроса. Публичная мастерская показывает безопасный порядок работы с данными, но не создаёт API совместного хранения автоматически.
Фрагмент файла src/model.mjs
export function parseNotes(text, track, duration) {
if (text.length > 32000) throw new Error('Файл заметок должен быть меньше 32 КБ.');
const doc = JSON.parse(text);
if (doc?.schema !== 1 || doc.track !== track || Math.abs(doc.duration - duration) > 0.05 || !Number.isFinite(doc.duration))
throw new Error('Заметки относятся к другой записи или версии формата.');
if (!Array.isArray(doc.regions) || doc.regions.length > 20) throw new Error('Допускается до 20 фрагментов.');
const ids = new Set();
return doc.regions.map((r, i) => {
if (!r || typeof r.start !== 'number' || typeof r.end !== 'number' || typeof r.label !== 'string')
throw new Error(`Неверные типы полей фрагмента ${i + 1}.`);
if (!r || typeof r.id !== 'string' || !/^[a-zA-Z0-9_-]{1,60}$/.test(r.id) || ids.has(r.id))
throw new Error(`Неверный или повторяющийся ID фрагмента ${i + 1}.`);
ids.add(r.id);
return { id: r.id, ...validateRegion(r.start, r.end, duration, r.label) };
});
}
Скачивание, Clipboard и освобождение временных URL
Для скачивания текста создаётся Blob, затем object URL и ссылка с download. После запуска скачивания временный URL освобождается. Сам JSON формируется в памяти браузера, поэтому сервер не принимает личные заметки пользователя. Для кодового файла используется тот же механизм с текстовым MIME.
Копирование может быть запрещено политикой iframe, разрешениями или небезопасным контекстом. В этом случае интерфейс предлагает выделить текст либо скачать файл и не сообщает ложный успех. Наличие объекта navigator.clipboard само по себе не доказывает выполнение операции: приложение ждёт завершения writeText.
При использовании Blob для больших данных учитывайте время жизни объектов и память. Не сохраняйте десятки ненужных URL после каждого изменения. Освобождение адреса после скачивания и уничтожение плеера при уходе решают разные задачи, поэтому нужны оба механизма. Подробности браузерного API описаны в документации revokeObjectURL.
Фрагмент файла src/app.mjs
function download(text,name,type='application/json') {
const url=URL.createObjectURL(new Blob([text],{type})); const a=document.createElement('a'); a.href=url;a.download=name;a.click();setTimeout(()=>URL.revokeObjectURL(url),1000);
}
Фрагмент файла src/app.mjs
async function copyText(text,statusId) {
try {await navigator.clipboard.writeText(text);$(statusId).textContent='Скопировано.';}
catch {$(statusId).textContent='Браузер не подтвердил копирование. Выделите текст вручную или скачайте файл.';}
}
Длинные записи, peaks и память браузера
Короткий WAV в мастерской удобен для обучения, но не является моделью загрузки большого архива разговоров. Полное декодирование длинного аудио может потребовать заметной памяти. Размер сжатого MP3 не равен размеру декодированных данных, поэтому оценивать нагрузку только по мегабайтам файла недостаточно.
Для длинных записей полезно изучить заранее подготовленные peaks и длительность, которые можно передать при загрузке. Волну тогда не обязательно каждый раз вычислять из всего аудио на клиенте. Это отдельный этап подготовки данных и отдельный контракт с хранилищем. В этой мастерской peaks заранее не подставляются: браузер действительно декодирует короткие WAV.
Учитывайте число одновременно существующих плееров, длину файлов, каналы, масштаб и память устройства. Один кабинет с выбранной записью часто проще и экономнее, чем десятки активных волн в списке. Начните с измерений своего сценария: время готовности, объём трафика, память и отзывчивость. Рекомендации по большим файлам и подготовленным peaks находятся в FAQ WaveSurfer.
CORS, MIME и почему браузер получает HTML вместо аудио
Если запись лежит на другом домене, сервер должен разрешать соответствующее чтение через CORS. Добавление произвольного заголовка в клиентском коде не превращает закрытый ресурс в доступный. В нашей мастерской WAV, модули и JSON раздаются с того же сайта, что уменьшает количество инфраструктурных переменных.
При ошибке сначала проверьте вкладку Network: точный URL, HTTP-код, Content-Type и содержимое ответа. Иногда сервер возвращает страницу ошибки или index.html с кодом 200 на любой неизвестный путь. Для аудио это не готовый файл, а причина последующего отказа декодирования. Отсутствующий ресурс должен давать явный 404.
Для модулей .mjs важен JavaScript MIME, для WAV — audio/wav. Публичному домену также нужен HTTPS, особенно если используется Clipboard. Когда аудио размещается за авторизацией, согласуйте cookies, сроки ссылок и кеширование; не отключайте проверки доступа ради устранения CORS. Основной механизм описан в руководстве MDN по CORS.
Linux/VPS: разместить готовую мастерскую через Nginx
Для публикации достаточно перенести содержимое public в отдельный каталог сайта. Постоянный Node-процесс и PHP-FPM этой мастерской не нужны: Node используется при сборке, а Nginx выдаёт статические файлы. В docs/linux-vps.md приведён пример для Debian или Ubuntu с обычным пользователем deploy, каталогом /srv/wavesurfer-demo/public и отдельным виртуальным хостом.
Перед применением замените домен и пользователя на свои значения. Скопируйте конфигурацию в новый файл, проверьте nginx -t и только затем выполняйте reload. Пример не удаляет чужие каталоги и не заменяет существующие сайты. Для обновлений сохраняйте предыдущую версию public, чтобы можно было вернуть рабочий release при ошибке.
Конфигурация ниже является HTTP-заготовкой. DNS и HTTPS настраиваются выбранным для сервера способом; сам материал не подтверждает выпуск сертификата на ваш домен. Дополнительные варианты разобраны в статье о Nginx и мастерской Caddy. После размещения отдельно откройте страницу, скачайте WAV и проверьте отсутствующий файл: успешное копирование папки ещё не является приёмкой.
Фрагмент файла docs/nginx.conf
server {
listen 80;
server_name audio.example.com;
root /srv/wavesurfer-demo/public;
index index.html;
include /etc/nginx/mime.types;
types { text/javascript mjs; }
location / { try_files $uri $uri/ =404; }
location ~* \.(wav|mp3|ogg|m4a|flac)$ {
try_files $uri =404;
add_header Cache-Control "public, max-age=3600";
}
location ~* \.(html|json|mjs|js|css)$ {
try_files $uri =404;
add_header Cache-Control "no-cache";
}
add_header X-Content-Type-Options nosniff always;
}
Фрагмент файла docs/linux-vps.md
cd wavesurfer-project
npm ci --ignore-scripts
npm run build
npm test
sudo install -d -m 755 -o deploy -g www-data /srv/wavesurfer-demo/public
rsync -a public/ /srv/wavesurfer-demo/public/
sudo cp docs/nginx.conf /etc/nginx/sites-available/wavesurfer-demo
sudo ln -s /etc/nginx/sites-available/wavesurfer-demo /etc/nginx/sites-enabled/wavesurfer-demo
sudo nginx -t
sudo systemctl reload nginx
Приватные записи и права доступа
В рабочем сервисе аудио может содержать персональные или внутренние данные. Проверка права должна выполняться при выдаче самой записи и её дополнительных данных, а не только при открытии страницы с кнопкой. Пользователь, которому скрыли плеер, не должен сохранять доступ к публичному URL файла.
Разделяйте авторизацию, срок жизни ссылок и кеширование. Подготовленные peaks тоже могут раскрывать сведения о записи, поэтому размещать их открыто по привычке не стоит. Не записывайте приватные подписанные URL в публичный просмотрщик исходников. Наш source-viewer уместен именно потому, что весь проект учебный и данные открыты.
Локальные заметки мастерской не сохраняются на сервер. Если добавить такое сохранение в продукт, понадобятся аутентификация, проверка прав, валидация и решение конфликтов. Начните с ясного контракта: кто редактирует, какую версию записи размечает, что считается успешным сохранением и как восстановить прежнее состояние. Эти правила стоит показать пользователю рядом с действиями, а не прятать в техническом описании.
Что проверяют тесты и что проверяется в браузере
На Windows с Node 24.19.0 и Linux с Node 24.22.2 прошли по десять тестов. Шестнадцать исходных файлов и пятнадцать ресурсов public, включая WAV и библиотеки, совпали между сборками побайтово. Linux-проверка выполнена в отдельном локальном контейнере; развёртывание на production VPS этим не заявляется.
Тесты проверяют ограничение позиции, допустимые границы, полный цикл JSON, отказ при неправильном документе, лимит локального файла, свойства авторских WAV, наличие API установленной библиотеки, соответствие source-viewer реальным файлам и работу настоящего HTTP-сервера на loopback. Отдельная регрессия сохраняет буквальный текст подписи: чтение HTML-представления региона не должно превращать амперсанд в повторно экранированную сущность.
HTTP-тест получает WAV, модуль и JSON с ожидаемыми MIME, проверяет 404 и попытку выхода за каталог. Аудиотест читает PCM и сравнивает файлы с результатом генератора. Это полезные исполняемые проверки проекта, но они не означают, что Node прослушал звук или отрисовал волну на телефоне.
В браузере отдельно нужно пройти запуск, паузу, переключение записей, отказ и восстановление, регионы, повтор, масштаб, экспорт и импорт. Для адаптивности проверяется общая ширина страницы и ширина плеера внутри iframe. После публикации дополнительно сверяются доступность модулей, WAV и ZIP. Сочетание этих проверок позволяет отличить исправные исходники от действительно работающей опубликованной мастерской.
Фрагмент файла README.md
npm run build
npm test
Как перенести пример в свой продукт
Выберите один сценарий и перенесите его целиком: например, карточку аудиозаписи с отмеченными фрагментами. Сначала замените учебную библиотеку списком своих разрешённых объектов. Сохраните явный запуск, состояние загрузки и восстановление после ошибки. Затем подключите серверное хранение заметок с версией записи и проверкой прав.
В интерфейсе показывайте человеку, что именно сохранено: локальный черновик, скачанный файл или принятая сервером ревизия. Не называйте выделение монтажом и не обещайте совместную работу до появления соответствующего протокола. Так приложение остаётся понятным даже при постепенном развитии: каждый новый шаг имеет проверяемый результат.
Весь проект доступен для изменения по MIT с сохранением лицензий зависимостей. Для дальнейшей работы используйте справочник методов WaveSurfer, официальный пример Regions и пример Timeline. Сначала повторите маленький опыт, затем адаптируйте данные и только после этого расширяйте масштаб. Такой порядок помогает получить полезный инструмент, которым удобно пользоваться каждый день.


