이 페이지에서

오디오 개요

음파

오디오 기능

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(&input);
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 형식의 파일을 지정할 수 있습니다.

조정할 수 있습니다:

저레벨 오디오 입력 및 출력

Qt Multimedia 의 C++ API는 오디오 입력 및 출력 기능에 대한 원시 액세스를 위한 클래스를 제공하여 애플리케이션이 마이크와 같은 장치에서 원시 데이터를 수신하고 스피커 또는 기타 장치에 원시 데이터를 쓸 수 있도록 합니다. 일반적으로 이러한 클래스는 오디오 디코딩이나 기타 처리를 수행하지 않지만 다양한 유형의 원시 오디오 데이터를 지원할 수 있습니다.

QAudioSink 클래스는 원시 오디오 데이터 출력을 제공하고 QAudioSource 클래스는 원시 오디오 데이터 입력을 제공합니다. 사용 가능한 하드웨어에 따라 사용 가능한 오디오 출력 및 입력이 결정됩니다.

QIODevice를 사용한 푸시 및 풀

로우 레벨 오디오 클래스는 pushpull 의 두 가지 모드로 작동할 수 있습니다. pull 모드에서 오디오 장치는 QIODevice 를 제공하여 시작됩니다. 출력 장치의 경우 QAudioSink 클래스는 더 많은 오디오 데이터가 필요할 때 QIODevice ( QIODevice::read() 사용)에서 데이터를 가져옵니다. 반대로 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 정보(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(); // 220Hz 사인파 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() 시그니처와 더불어,  백엔드가 콜백 기반 IO를 구현하지 않는  경우 // *  오디오 콜백  시작은 실패합니다 (API는 모든 주요  플랫폼에서  사용 가능 ) // * 오디오 콜백의 서명이 format.sampleFormat()과 일치하지  않습니다 .
        qWarning() << "Error starting audio output:" << audio->errorString();
    } }

참고: 이 API는 콜백 API를 지원하는 플랫폼에서만 사용할 수 있습니다: Apple의 CoreAudio(macOS, iOS 등), Windows, Linux(PulseAudio 또는 PipeWire 백엔드 사용) 및 Android.

참고: 콜백은 소프트 실시간 오디오 스레드에서 호출됩니다. 오디오 글리치 또는 드롭아웃이 발생할 수 있으므로 콜백이 차단되지 않도록 하는 것이 중요합니다. 여기에는 IO 차단, 뮤텍스 잠금, 메모리 할당 또는 기타 차단할 수 있는 모든 작업을 수행하는 것이 포함됩니다. 모범 사례는 Ross Bencina의 실시간 오디오 프로그래밍 101: 시간은 아무것도 기다리지 않는다 문서를 참조하세요. 또한 clang의 실시간 새니타이저를 사용하여 오디오 콜백의 유효성을 검사하는 것도 고려해 보세요.

압축된 오디오를 메모리로 디코딩하기

압축된 오디오 파일을 디코딩하고 추가 처리를 직접 수행해야 하는 경우가 있습니다. 예를 들어, 여러 샘플을 믹싱하거나 사용자 지정 디지털 신호 처리 알고리즘을 사용하는 경우 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 모듈은 3D 공간에서 음장을 구현하기 위한 API를 제공합니다.

참조 문서

C++ 클래스

QAmbientSound

스테레오 오버레이 사운드

QAudioBuffer

특정 포맷과 샘플 레이트를 가진 오디오 샘플 컬렉션을 나타냅니다.

QAudioBufferInput

QMediaCaptureSession을 통해 QMediaRecorder에 커스텀 오디오 버퍼를 제공하는 데 사용됩니다.

QAudioBufferOutput

QMediaPlayer에서 제공하는 오디오 데이터를 캡처하는 데 사용됩니다.

QAudioDecoder

오디오 디코딩 구현

QAudioDevice

오디오 장치 및 해당 기능에 대한 정보

QAudioEngine

3차원 음장 관리

QAudioFormat

오디오 스트림 파라미터 정보 저장

QAudioInput

오디오 입력 채널을 나타냅니다.

QAudioListener

QAudioEngine에 의해 정의된 음장을 듣는 사람의 위치와 방향을 정의합니다.

QAudioOutput

오디오 출력 채널을 나타냅니다.

QAudioRoom

QAudioSink

오디오 출력 장치로 오디오 데이터를 전송하기 위한 인터페이스

QAudioSource

오디오 입력 장치에서 오디오 데이터를 수신하기 위한 인터페이스

QMediaCaptureSession

오디오 및 비디오 콘텐츠의 캡처를 허용합니다.

QMediaRecorder

캡처 세션 인코딩 및 녹화에 사용

QSoundEffect

지연 시간이 짧은 사운드 효과를 재생하는 방법

QSpatialSound

3D 공간의 사운드 오브젝트

QtAudio

오디오 클래스에서 사용하는 열거형 포함

QML 유형

AmbientSound

스테레오 오버레이 사운드

AudioEngine

3D 씬 내부의 사운드 오브젝트를 관리합니다.

AudioInput

캡처 세션에서 오디오를 캡처하는 데 사용할 오디오 입력입니다.

AudioListener

오디오 엔진에 의해 정의된 사운드 필드를 듣는 사람의 위치와 방향을 정의합니다.

AudioOutput

캡처 세션의 재생 또는 모니터링에 사용할 오디오 출력입니다.

AudioRoom

CaptureSession

오디오 및 비디오 콘텐츠의 캡처를 허용합니다.

MediaPlayer

씬에 미디어 재생을 추가합니다.

MediaRecorder

캡처 세션에서 생성된 미디어 인코딩 및 녹화용

PlaybackOptions

로우 레벨 미디어 재생 옵션

SoundEffect

유형은 QML에서 사운드 효과를 재생하는 방법을 제공합니다.

SpatialSound

3D 공간의 사운드 오브젝트

audioDevice

오디오 장치를 설명합니다.

mediaMetaData

미디어 파일에 대한 메타 데이터 제공

예제

Audio Devices Example

사용 가능한 오디오 장치와 해당 구성을 나열합니다.

Audio Output Example

QAudioSink 클래스를 사용하여 오디오 재생 활성화하기.

Audio Recorder Example

사용 가능한 장치 및 지원되는 코덱 검색하기.

Audio Source Example

QAudioSource 클래스를 사용하여 오디오 녹음하기.

Spatial Audio Panning Example

Qt의 공간 오디오 엔진의 일부 기능을 보여줍니다.

© 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.