오디오 개요

오디오 기능
Qt Multimedia 이 과정은 오디오 입력, 출력 및 처리에 대한 저수준 및 고수준 접근 방식을 모두 다루는 다양한 오디오 강좌를 제공합니다.
오디오 구현 세부 사항
압축 오디오 재생
단순한 비압축 오디오가 아닌 미디어 또는 오디오 파일을 재생하려면 ` QMediaPlayer ` C++ 클래스나 ` MediaPlayer ` QML 타입을 사용할 수 있습니다. 또한 ` QMediaPlayer ` 클래스와 관련 QML 타입은 필요한 경우 비디오도 재생할 수 있습니다.
자세한 내용은 ‘지원되는 미디어 형식’을 참조하십시오.
오디오를 재생하려면 미디어 플레이어를 QAudioOutput 객체(또는 QML의 AudioOutput 요소)에 연결해야 합니다.
다음은 C++을 사용하여 로컬 파일을 재생하는 방법입니다:
player = new QMediaPlayer;
audioOutput = new QAudioOutput;
player->setAudioOutput(audioOutput);
// ...
player->setSource(QUrl::fromLocalFile("/Users/me/Music/coolsong.mp3"));
audioOutput->setVolume(0.5);
player->play();QML에서 동일한 기능을 구현하는 방법은 다음과 같습니다:
MediaPlayer {
audioOutput: AudioOutput {}
source: "file:///path/to/my/music.mp3"
Component.onCompleted: { play() }
}파일에 오디오 녹음하기
오디오를 파일에 녹음하려면 캡처 세션을 생성하고, 여기에 오디오 입력 소스와 레코더를 연결해야 합니다. 이러한 요소들은 ` QMediaCaptureSession`, ` QAudioInput`, ` QMediaRecorder ` 클래스를 통해 구현됩니다. 기본 생성된 ` QAudioInput `는 시스템의 기본 오디오 입력 소스를 선택합니다. 레코더는 간단한 record() 및 stop() 함수를 통해 녹음 과정을 제어합니다. 또한 이를 사용하여 출력 위치, 오디오 인코더 또는 파일 컨테이너 형식을 선택할 수 있습니다.
C++에서 기본 마이크를 통해 오디오를 녹음하는 세션은 다음과 같습니다:
QMediaCaptureSession session;
QAudioInput audioInput;
session.setAudioInput(&audioInput);
QMediaRecorder recorder;
session.setRecorder(&recorder);
recorder.setQuality(QMediaRecorder::HighQuality);
recorder.setOutputLocation(QUrl::fromLocalFile("test.mp3"));
recorder.record();QML에서는 다음과 같이 동일한 결과를 얻을 수 있습니다:
CaptureSession {
audioInput: AudioInput {}
mediaRecorder: MediaRecorder {
id: recorder
outputLocation: "file:///path/to/test.mp3"
}
Component.onCompleted: { recorder.record() }
}QMediaCaptureSession 또한 이미지 캡처나 동영상 녹화와 같은 더 복잡한 사용 사례도 지원합니다.
저지연 음향 효과
사운드 장치에 대한 직접적인 액세스 외에도, ` QSoundEffect ` 클래스(및 ` SoundEffect ` QML 유형)는 사운드를 재생하는 보다 추상적인 방법을 제공합니다. 이 클래스를 사용하면 WAV 형식 파일을 지정할 수 있으며, 필요한 경우 저지연으로 해당 파일을 재생할 수 있습니다.
다음 항목을 조정할 수 있습니다:
- Number of loops 사운드 효과가 재생되는 방식을 조정할 수 있습니다.
- Volume 사운드 효과의 재생 시간.
- Muting 음향 효과의.
저수준 오디오 입력 및 출력
Qt Multimedia 의 C++ API는 오디오 입력 및 출력 기능에 대한 원시 액세스를 제공하는 클래스를 제공하며, 이를 통해 애플리케이션은 마이크와 같은 장치로부터 원시 데이터를 수신하고, 스피커나 기타 장치에 원시 데이터를 출력할 수 있습니다. 일반적으로 이러한 클래스는 오디오 디코딩이나 기타 처리를 수행하지 않지만, 다양한 유형의 원시 오디오 데이터를 지원할 수 있습니다.
QAudioSink 클래스는 원시 오디오 데이터 출력을 제공하며, QAudioSource 는 원시 오디오 데이터 입력을 제공합니다. 사용 가능한 하드웨어에 따라 어떤 오디오 출력 및 입력이 지원되는지가 결정됩니다.
QIODevice를 사용한 Push 및 Pull
저수준 오디오 클래스는 ‘ push ’과 ‘ pull ’의 두 가지 모드로 작동할 수 있습니다. ‘ pull ’ 모드에서는 ‘ QIODevice ’을 전달하여 오디오 장치를 시작합니다. 출력 장치의 경우, ‘ QAudioSink ’ 클래스는 추가 오디오 데이터가 필요할 때 ‘ QIODevice::read()’를 사용하여 ‘ QIODevice ’에서 데이터를 가져옵니다. 반대로, ‘ QAudioSource ’을 사용하는 ‘ pull ’ 모드의 경우, 오디오 데이터가 준비되면 해당 데이터가 ‘ QIODevice ’에 직접 기록됩니다.
push 모드에서는 오디오 장치가 필요에 따라 쓰기 또는 읽기가 가능한 QIODevice 인스턴스를 제공합니다.
참고: QIODevice 는 오디오 장치에 즉시 액세스하지 않고, 대신 데이터를 내부적으로 버퍼링합니다. 즉, QIODevice 를 사용하여 애플리케이션 스레드에서 언제든지 데이터를 쓰거나 읽을 수 있으며, 일반적으로 250ms의 버퍼링 시간이 추가됩니다. 애플리케이션이 QIODevice 에 오디오 데이터를 충분히 빠르게 전달하지 못하거나( QAudioSink 참조) QIODevice 에서 데이터를 충분히 빠르게 읽지 못하면 오디오 끊김 현상이 발생합니다.
콜백 기반 인터페이스
QIODevice 기반 인터페이스 외에도, 저수준 오디오 클래스는 사용자가 콜백을 등록할 수 있는 콜백 기반 인터페이스를 제공합니다. 이 콜백은 오디오 장치가 더 많은 데이터를 필요로 하거나 전달할 때마다 오디오 스레드에서 호출됩니다. 이를 통해 애플리케이션이 오디오 스레드에서 직접 데이터를 처리할 수 있으므로, 훨씬 더 낮은 지연 시간을 가진 오디오 처리가 가능합니다.
{
QAudioFormat format;
// 포맷 설정, 예:
format.setSampleRate(44100);
format.setChannelCount(2);
format.setSampleFormat(QAudioFormat::Float);
QAudioDevice info(QMediaDevices::defaultAudioOutput());
if (!info.isFormatSupported(format)) {
qWarning() << "Raw audio format not supported by backend, cannot play audio.";
return;
}
audio = new QAudioSink(format, this);
float phaseIncrement = 2 * M_PI * 220.0 / format.sampleRate(); // 220 Hz 사인파
audio->start([&phase, phaseIncrement] (QSpan<float> interleavedAudioBuffer) {
// 오디오 콜백은 잠재적으로 블록킹을 유발할 수 있는 함수를 호출해서는 안 됩니다
// 오디오 버퍼를 사인파로 채웁니다
const int sampleCount = interleavedAudioBuffer.size() / 2; // 스테레오이므로 2로 나눕니다
for (int i = 0; i < sampleCount;++i) {
float sample = std::sin(phase);
interleavedAudioBuffer[i * 2] = sample; // 왼쪽 채널
interleavedAudioBuffer[i * 2 + 1] = sample; // 오른쪽 채널
phase+= phaseIncrement; // 다음 샘플을 위해 위상 증가
}
});
if (!audio->error()== QtAudio::Error::NoError) {
// 다른 start() 시그니처 외에도, 다음의 경우 오디오 콜백 시작이 실패합니다.
// * 백엔드가 콜백 기반 I/O를 구현하지 않은 경우 (이 API는 모든 주요
// 플랫폼에서 사용할 수 있음 )
// * 오디오 콜백의 시그니처가 format.sampleFormat()과 일치하지 않는 경우
qWarning() << "Error starting audio output:" << audio->errorString();
}
}참고: 이 API는 콜백 API를 지원하는 플랫폼(Apple의 CoreAudio(macOS, iOS 등), Windows, Linux(PulseAudio 또는 PipeWire 백엔드 사용), Android)에서만 사용할 수 있습니다.
참고: 콜백은 소프트 실시간 오디오 스레드에서 호출됩니다. 콜백이 차단되지 않도록 하는 것이 중요합니다. 차단될 경우 오디오 글리치나 끊김 현상이 발생할 수 있습니다. 여기에는 차단형 I/O 수행, 뮤텍스 잠금, 메모리 할당 또는 차단될 가능성이 있는 기타 모든 작업이 포함됩니다. 모범 사례에 대해서는 Ross Bencina의 기사 “Real-time audio programming 101: time waits for nothing”을 참고하십시오. 또한 오디오 콜백을 검증하기 위해 clang의 Realtime sanitizer 사용을 고려해 보십시오.
압축된 오디오를 메모리로 디코딩하기
경우에 따라 압축된 오디오 파일을 디코딩하여 직접 추가 처리를 수행하고 싶을 수 있습니다. 예를 들어, 여러 샘플을 믹싱하거나 사용자 정의 디지털 신호 처리 알고리즘을 사용하는 경우입니다. ` QAudioDecoder `는 로컬 파일이나 ` QIODevice ` 인스턴스의 데이터 스트림을 디코딩하는 기능을 지원합니다.
다음은 로컬 파일을 디코딩하는 예시입니다:
QAudioFormat desiredFormat;
desiredFormat.setChannelCount(2);
desiredFormat.setSampleFormat(QAudioFormat::Int16);
desiredFormat.setSampleRate(48000);
QAudioDecoder *decoder = new QAudioDecoder(this);
decoder->setAudioFormat(desiredFormat);
decoder->setSource("level1.mp3");
connect(decoder, &QAudioDecoder::bufferReady, this, &AudioDecodingExample::readBuffer);
decoder->start();
// Now wait for bufferReady() signal and call decoder->read()공간 오디오
이 Qt Spatial Audio 이 모듈은 3차원 공간에서 음장을 구현하기 위한 API를 제공합니다.
참조 문서
C++ 클래스
스테레오 오버레이 사운드 | |
특정 형식과 샘플 레이트를 가진 오디오 샘플 모음을 나타냅니다 | |
QMediaCaptureSession을 통해 QMediaRecorder에 사용자 정의 오디오 버퍼를 제공하는 데 사용됩니다 | |
QMediaPlayer에서 제공하는 오디오 데이터를 캡처하는 데 사용됩니다 | |
오디오 디코딩을 구현합니다 | |
오디오 장치 및 그 기능에 대한 정보 | |
3차원 음장을 관리합니다 | |
오디오 스트림 매개변수 정보를 저장합니다 | |
오디오 입력 채널을 나타냅니다 | |
QAudioEngine에 의해 정의된 음장을 청취하는 사람의 위치와 방향을 정의합니다 | |
오디오 출력 채널을 나타냅니다 | |
오디오 출력 장치로 오디오 데이터를 전송하기 위한 인터페이스 | |
오디오 입력 장치로부터 오디오 데이터를 수신하기 위한 인터페이스 | |
오디오 및 비디오 콘텐츠를 캡처할 수 있게 합니다 | |
캡처 세션을 인코딩하고 녹화하는 데 사용됩니다 | |
지연 시간이 짧은 음향 효과를 재생하는 방법 | |
3D 공간 내의 사운드 객체 | |
오디오 클래스에서 사용하는 열거형을 포함합니다 |
QML 유형
스테레오 오버레이 사운드 | |
3D 장면 내의 사운드 객체를 관리합니다 | |
캡처 세션에서 오디오를 캡처하는 데 사용되는 오디오 입력 | |
AudioEngine에 의해 정의된 음장을 청취하는 사람의 위치와 방향을 정의합니다 | |
캡처 세션의 재생 또는 모니터링에 사용되는 오디오 출력 | |
오디오 및 비디오 콘텐츠 캡처를 가능하게 합니다 | |
씬에 미디어 재생 기능을 추가합니다 | |
CaptureSession에서 생성된 미디어를 인코딩하고 기록하기 위한 용도 | |
저수준 미디어 재생 옵션 | |
이 타입은 QML에서 음향 효과를 재생하는 방법을 제공합니다 | |
3D 공간 내의 사운드 객체 | |
오디오 장치를 설명합니다 | |
미디어 파일에 대한 메타데이터를 제공합니다 |
예제
사용 가능한 오디오 장치와 해당 구성 정보를 나열합니다. | |
QAudioSink 클래스를 사용하여 오디오 재생을 활성화합니다. | |
사용 가능한 장치와 지원되는 코덱을 확인합니다. | |
QAudioSource 클래스를 사용하여 오디오 녹음하기. | |
Qt Spatial Audio 엔진이 제공하는 몇 가지 기능을 보여줍니다. |
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.