Импорт звука: WAV, Vorbis и MP3
Параметры WAV, единицы петли, музыкальные метаданные и отличие импорта от прямой загрузки.
Импортируйте WAV, Ogg Vorbis или MP3, затем загружайте исходный путь ресурса. Редактор сохраняет параметры рядом с исходником и создаёт ресурс воспроизведения в кеше. Изменение настроек импорта не переписывает исходную запись.
Импортировать и воспроизвести звук
- Поместите корректный PCM WAV в Audio/pcm.wav внутри проекта.
- Выберите файл в Content Browser. Для первой проверки установите в Import параметр compress/mode в PCM (Uncompressed), затем примените Reimport.
- Создайте AudioStreamPlayer, оставьте Autoplay выключенным и прикрепите полный ImportedSound.cs:
using Reckfell;
public partial class ImportedSound : AudioStreamPlayer
{
public override void _Ready()
{
Stream = ResourceLoader.Load<AudioStream>("asset://Audio/pcm.wav");
if (Stream == null)
{
ReckfellApi.PushError("Cannot load asset://Audio/pcm.wav");
return;
}
Play();
}
}Запустите уровень. Звук без петли проиграется один раз; при естественном завершении приходит Finished. Если звук не слышен, сначала проверьте шину проигрывателя, заглушение, громкость и устройство вывода. Руководство по аудиопотокам разбирает воспроизведение, паузу, остановку и пространственные проигрыватели.
Формат и размер
| Исходник | Ресурс C# после импорта | С чего начать |
|---|---|---|
| WAV | AudioStreamWav | Эффекты, которым нужен контроль PCM или обработка при импорте WAV |
| Ogg Vorbis | AudioStreamOggVorbis | Закодированная музыка, окружение или речь |
| MP3 | AudioStreamMP3 | Готовые MP3 или выбор по измерениям на целевой платформе |
Импортер WAV по умолчанию использует сжатие Quite OK Audio, а не несжатый PCM. PCM, IMA ADPCM и QOA — разные варианты результата. Одно расширение .ogg не доказывает кодек Vorbis: проверьте кодек файла. Переименование не преобразует формат.
Для несжатого PCM: байты = длительность × частота дискретизации × число каналов × байты на отсчёт. Одна секунда стерео 16 бит при 48 000 Гц содержит 192 000 байт аудиоданных без заголовка контейнера. Это не прогноз для сжатых файлов. Сравнивайте свои записи и измерения на целевом устройстве: формат не гарантирует заданное число голосов, порядок нагрузки на процессор или одинаковое воспринимаемое качество при конкретном размере.
Параметры WAV
Пути ниже обозначают параметры Import. После изменения применяйте Reimport.
| Параметр | Действие и ограничение |
|---|---|
| compress/mode | 0: PCM; 1: IMA ADPCM; 2: Quite OK Audio, стандартное значение импортера |
| force/8_bit | Выбирает 8-битный результат для PCM. При сжатии формат результата по-прежнему определяется выбранным кодеком |
| force/mono | Усредняет каналы стерео. Может уменьшить объём PCM; противофазные каналы могут взаимно погаситься |
| force/max_rate | Включает ограничение частоты дискретизации |
| force/max_rate_hz | Предел при включённом force/max_rate; более высокий предел не повышает частоту исходника |
| edit/normalize | Масштабирует сигнал по пику до последующей обработки; не выравнивает воспринимаемую громкость и не ограничивает уровень шины |
| edit/trim | Удаляет тихие участки по краям с текущим порогом −50 дБ; может убрать намеренно тихое затухание |
| edit/loop_mode | 0: определить из WAV; 1: выключить; 2: вперёд; 3: туда-обратно; 4: назад |
| edit/loop_begin / edit/loop_end | Явные точки петли WAV в кадрах отсчётов, не в секундах и не в значениях чередующихся каналов |
Для предела 24 000 Гц включите force/max_rate и задайте force/max_rate_hz = 24000. Одно изменение числового поля не включает ограничение. Понижение частоты меняет объём данных, сохраняя примерно ту же длительность; оцените звук, а не считайте преобразование заведомо незаметным.
Нормализация выполняется до обрезки. Текущая реализация Trim затухает в конце на участке до 500 кадров, но не обещает аналогичного нарастания в начале. При 48 000 Гц это около 10,4 мс, а не 500 мс. При обнаруженной петле WAV обрезка пропускается. Явное переопределение петли применяется позже, поэтому выбор Forward не гарантирует защиту исходника без метаданных от Trim. После обрезки или изменения частоты заново проверьте точки петли.
Не считайте, что исходник высокой разрядности становится ресурсом воспроизведения той же разрядности. Проверяйте Format, MixRate, Stereo и GetLength импортированного AudioStreamWav. Data содержит выбранную кодировку результата и не всегда является массивом сырого PCM.
Единицы петли WAV
При 48 000 Гц точка 0,25 секунды соответствует кадру 12000, в том числе для стерео. Не умножайте на два канала. Явные точки относятся к обработанному звуку. В текущем импортере конец −1 преобразуется в число кадров минус один: для проверенного образца из 48 000 кадров LoopEnd равен 47999.
Detect From WAV читает поддерживаемые метаданные петли smpl. Disabled игнорирует эту петлю. В числах параметра импорта есть дополнительный пункт Detect; не передавайте их напрямую как значения AudioStreamWav.LoopModeEnum.
Проверяйте границы прослушиванием. Правильные сохранённые точки и поддерживаемый режим не доказывают бесшовность. Зацикленный проигрыватель не завершается естественно при каждом повторе; для завершения вызывайте Stop.
Параметры Ogg Vorbis и MP3
| Параметр | Значение |
|---|---|
| loop | Включить повтор |
| loop_offset | Позиция возврата в секундах после достижения границы петли; используется при повторе |
| bpm | Авторский темп в долях в минуту для музыкального времени |
| beat_count | Число долей, описывающих музыкальный фрагмент |
| bar_beats | Число долей в такте: например, 4 для четырёхдольного такта |
Эти форматы не предоставляют независимый конец петли, обратный ход и движение туда-обратно через параметры импорта WAV. Музыкальные метаданные не определяют темп автоматически и сами по себе не растягивают запись во времени. Задавайте их по настоящей композиции: ошибочный темп может сдвинуть границу интерактивной музыки.
Импортер предоставляет диалог Advanced для петли и музыкальных метаданных. Reimport применяет сохранённые параметры импорта. Автоматическая проверка этого руководства меняет те же параметры в метаданных; она не подтверждает работу мышью и звуковое предпрослушивание диалога.
Диагностика импортированного звука
Для ресурсов проекта ResourceLoader.Load использует результат импорта и его настройки. Статические AudioStreamWav.LoadFromFile, AudioStreamOggVorbis.LoadFromFile и AudioStreamMP3.LoadFromFile читают сырой файл напрямую и не применяют параметры .import редактора. Для WAV при необходимости передайте настройки преобразования явно: пустой словарь выбирает PCM, а не стандартный QOA импортера. Для Ogg/MP3 задайте петлю и музыкальные свойства загруженного ресурса самостоятельно. Перед выбором этого сценария убедитесь, что сырой файл действительно доступен в экспортированной сборке.
| Симптом | Что проверить |
|---|---|
| Ресурс отсутствует или ошибка декодирования | Настоящий формат/кодек, сообщения импорта и поддержку формата в сборке |
| Размер WAV почти не изменился после настройки | Повторный импорт, сжатие, каналы и включение ограничения частоты |
| В моно звук почти исчез | Фазы каналов стерео и их усреднение |
| Тихий хвост или намеренная пауза исчезли | Trim; сравните с импортом без обрезки |
| Петля начинается не там | Кадры WAV против секунд Ogg/MP3, частоту обработанного звука и обрезку |
| Импорт стал громче, но смесь перегружается | Нормализацию по пику и суммарные уровни шин: нормализация не является лимитером микса |
| Finished не приходит | Петлю, явный Stop и остальные условия воспроизведения из руководства по аудиопотокам |
В движке проверены настоящий импорт, неизменность байтов исходников, преобразования WAV и метаданные петли, музыкальные параметры Ogg/MP3, точный пример C# и декодированный PCM, захваченный из микшера для PCM/QOA/ADPCM/Vorbis/MP3. Микшер использует драйвер Dummy: это проверка аудиоданных, а не звука колонок, качества на слух или производительности. Форма волны на границах/направлениях петли, все варианты WAV, интерфейс редактора и браузерные, мобильные или экспортированные сборки здесь не проверены.