Импорт аудио

Обзор

Процесс импорта аудио во время выполнения можно разбить на несколько этапов:

1. Создание Runtime Audio Importer
2. Привязка к необходимым делегатам (OnProgress и OnResult)
3. Импорт аудио из файла или буфера
4. Воспроизведение импортированного Sound Wave, полученного из делегата OnResult (подробнее здесь)

Важное замечание

Убедитесь, что экземпляры Runtime Audio Importer и Sound Wave не будут преждевременно удалены сборщиком мусора, сохраняя на них жёсткую ссылку. Это можно сделать, присвоив их отдельным переменным с использованием UPROPERTY(), TStrongObjectPtr или любого другого метода, предотвращающего уничтожение объекта.

Поддерживаемые аудиоформаты

Runtime Audio Importer поддерживает импорт следующих аудиоформатов:

Формат	Описание
MP3	MPEG-1/2/2.5 Audio Layer I/II/III
WAV	Waveform Audio File Format
FLAC	Free Lossless Audio Codec
OGG VORBIS	Ogg-контейнер с аудио Vorbis
OGG OPUS	Ogg-контейнер с аудио Opus
BINK	Bink Audio
RAW (PCM)	Несжатые аудиоданные в формате Pulse-Code Modulation (Int8, UInt8, Int16, UInt16, Int32, UInt32, Float32)

подсказка

При импорте аудио вы можете явно указать формат или использовать автоматическое определение формата на основе расширения файла или его содержимого.

Потоковый импорт аудио

Для сценариев потоковой передачи, где аудиоданные поступают постепенно (например, с сервера, в реальном времени или из сетевых потоков), рассмотрите использование Streaming Sound Waves.

Этот метод предоставляет возможность непрерывного добавления аудиоданных в буфер одного и того же Sound Wave, что делает его подходящим для живых трансляций или больших файлов, обрабатываемых по частям. Подробнее см. в документации Streaming Sound Wave.

Основные шаги реализации

1. Создание Runtime Audio Importer

Сначала необходимо создать объект Runtime Audio Importer. Убедитесь, что он обрабатывается сборщиком мусора как сильная ссылка.

Blueprint

C++

Header, in the UCLASS declaration (.h)

// UPROPERTY() is used here to prevent the object from being prematurely garbage collected
UPROPERTY()
class URuntimeAudioImporterLibrary* Importer;

Source file, in the function where you want to create the importer (.cpp)

Importer = URuntimeAudioImporterLibrary::CreateRuntimeAudioImporter();

2. Привязка к делегату OnProgress

Для отслеживания прогресса импорта аудиоданных вы можете привязаться к делегату OnProgress (Blueprints) / OnProgressNative (C++).

Blueprint

C++

// Assuming Importer is a UE reference to a URuntimeAudioImporterLibrary object
// AddWeakLambda is used just as an example. You can use any other method to bind the delegate, such as AddUObject, AddUFunction, etc.
Importer->OnProgressNative.AddWeakLambda(this, [](int32 Percentage)
{
	UE_LOG(LogTemp, Log, TEXT("Import progress: %d"), Percentage);
});

подсказка

Это позволит вам отслеживать прогресс и, например, реализовать экран загрузки.

3. Привязка к делегату OnResult

Чтобы получать уведомления о завершении процесса импорта аудиоданных и получить доступ к ссылке на результирующую звуковую волну, необходимо привязаться к делегату OnResult (Blueprints) / OnResultNative (C++).

Blueprint

C++

// Assuming Importer is a UE reference to a URuntimeAudioImporterLibrary object
// AddWeakLambda is used just as an example. You can use any other method to bind the delegate, such as AddUObject, AddUFunction, etc.
Importer->OnResultNative.AddWeakLambda(this, [](URuntimeAudioImporterLibrary* Importer, UImportedSoundWave* ImportedSoundWave, ERuntimeImportStatus Status)
{
	UE_LOG(LogTemp, Log, TEXT("Import result: %s"), *UEnum::GetValueAsString(Status));
});

warning

Убедитесь, что импортированная звуковая волна обрабатывается сборщиком мусора как сильная ссылка, чтобы предотвратить преждевременное удаление. Это можно сделать, поместив её в отдельную переменную в Blueprints.

4. Начало импорта аудио

Запустите процесс импорта аудио, вызвав соответствующую функцию, которая может обрабатывать как сжатые, так и несжатые форматы аудиоданных.

Blueprint

C++

// Assuming Importer is a UE reference to a URuntimeAudioImporterLibrary object

// Import audio from a file
Importer->ImportAudioFromFile(TEXT("C:/Folder/AudioFile.mp3"), ERuntimeAudioFormat::Auto);

// Import audio from a buffer
TArray<uint8> AudioData = ...; // Fill the array with your audio data
Importer->ImportAudioFromBuffer(MoveTemp(AudioData), ERuntimeAudioFormat::OggVorbis);

// Import audio from a RAW file
Importer->ImportAudioFromRAWFile(TEXT("C:/Folder/AudioFile.raw"), ERuntimeRAWAudioFormat::Int8, 44100, 2);

// Import audio from a RAW buffer
TArray<uint8> RAWBuffer = ...; // Fill the array with your PCM int 16-bit audio data
Importer->ImportAudioFromRAWBuffer(MoveTemp(RAWBuffer), ERuntimeRAWAudioFormat::Int16, 44100, 2);

Вспомогательные функции

Поиск аудиофайлов

Вы можете сканировать директорию на наличие поддерживаемых аудиофайлов:

Blueprint

C++

URuntimeAudioUtilities::ScanDirectoryForAudioFiles(TEXT("C:/Folder/"), true,
	FOnScanDirectoryForAudioFilesResultNative::CreateWeakLambda(this, [this](bool bSucceeded, const TArray<FString>& AudioFilePaths)
	{
		// Handle the result
	}));

Полный пример

Вот полный пример реализации для импорта аудио:

Blueprint

C++

Это базовый пример кода для импорта аудио из файла.

Пример использует функцию ImportAudioExample, расположенную в классе UImportAudioClassExample внутри модуля EXAMPLEMODULE.

примечание

Для успешного запуска примера убедитесь, что добавили модуль RuntimeAudioImporter либо в PublicDependencyModuleNames, либо в PrivateDependencyModuleNames в файле .Build.cs, а также в файл .uproject вашего проекта.

// Пример функции импорта аудио
void UImportAudioClassExample::ImportAudioExample()
{
    // Путь к аудиофайлу
    FString AudioFilePath = TEXT("C:/AudioFiles/example.wav");
    
    // Создаем импортер
    URuntimeAudioImporter* AudioImporter = URuntimeAudioImporter::CreateRuntimeAudioImporter();
    
    // Импортируем аудио
    AudioImporter->ImportAudioFromFile(AudioFilePath, FOnAudioImportResult::CreateLambda(
        [](URuntimeAudioImporter* Importer, UImportedSoundWave* ImportedSoundWave, ETranscodingStatus Status)
        {
            if (Status == ETranscodingStatus::Successful)
            {
                UE_LOG(LogTemp, Display, TEXT("Аудио успешно импортировано!"));
            }
            else
            {
                UE_LOG(LogTemp, Error, TEXT("Ошибка импорта аудио!"));
            }
        }
    ));
}

Header file (.h)

#pragma once

#include "CoreMinimal.h"
#include "UObject/Object.h"
#include "ImportAudioClassExample.generated.h"

UCLASS(BlueprintType)
class EXAMPLEMODULE_API UImportAudioClassExample : public UObject
{
	GENERATED_BODY()

public:
	UFUNCTION(BlueprintCallable)
	void ImportAudioExample();

private:
	// Please pay attention to making the RuntimeAudioImporter a hard reference, such as using UPROPERTY(), to prevent it from being prematurely garbage collected
	UPROPERTY()
	class URuntimeAudioImporterLibrary* RuntimeAudioImporter;
};

Source file (.cpp)

#include "ImportAudioClassExample.h"
#include "RuntimeAudioImporterLibrary.h"

void UImportAudioClassExample::ImportAudioExample()
{
	RuntimeAudioImporter = URuntimeAudioImporterLibrary::CreateRuntimeAudioImporter();

	if (!IsValid(RuntimeAudioImporter))
	{
		UE_LOG(LogTemp, Error, TEXT("Failed to create audio importer"));
		return;
	}

	RuntimeAudioImporter->OnProgressNative.AddWeakLambda(this, [](int32 Percentage)
	{
		UE_LOG(LogTemp, Log, TEXT("Audio importing percentage: %d"), Percentage);
	});

	RuntimeAudioImporter->OnResultNative.AddWeakLambda(this, [this](URuntimeAudioImporterLibrary* Importer, UImportedSoundWave* ImportedSoundWave, ERuntimeImportStatus Status)
	{
		if (Status == ERuntimeImportStatus::SuccessfulImport)
		{
			UE_LOG(LogTemp, Warning, TEXT("Successfully imported audio with sound wave %s"), *ImportedSoundWave->GetName());
			// Here you can handle ImportedSoundWave playback, like "UGameplayStatics::PlaySound2D(GetWorld(), ImportedSoundWave);"
		}
		else
		{
			UE_LOG(LogTemp, Error, TEXT("Failed to import audio"));
		}

		RuntimeAudioImporter = nullptr;
	});

	RuntimeAudioImporter->ImportAudioFromFile(TEXT("C:/Folder/Example.mp3"), ERuntimeAudioFormat::Auto);
}