Qt Multimedia
Qt Multimedia 멀티미디어 콘텐츠를 처리하기 위한 다양한 QML 유형과 C++ 클래스를 제공하는 추가 모듈이 있습니다. 이 모듈에는 오디오 및 비디오 파일을 재생하고 화면에 렌더링하기 위한 사용하기 쉬운 API는 물론, 시스템 카메라 및 마이크, 화면 또는 창 캡처, 오디오 또는 비디오 메모리 버퍼를 포함한 다양한 소스에서 오디오 및 비디오를 녹화하기 위한 포괄적인 API가 포함되어 있습니다.
이 모듈의 기능은 다음과 같은 하위 모듈로 나뉩니다.
| Qt Multimedia | 멀티미디어 관련 사용 사례에 필요한 API를 제공합니다. |
| Qt Multimedia 위젯 | 위젯 기반의 멀티미디어 API를 제공합니다. |
| Qt Spatial Audio | 3D 공간에서 사운드 필드를 구현하기 위한 API를 제공합니다. |
시작하기
Qt 5에서 Qt 6으로 이식하는 경우, Qt Multimedia 의 변경 사항을 참조하십시오.
Qt Multimedia 를 처음 사용하는 경우, .qml 파일에 다음 문장을 사용하여 QML 유형을 애플리케이션으로 가져올 수 있습니다.
import QtMultimediaC++ 라이브러리와 링크하려면 프로젝트의 CMakeLists.txt 파일에 다음 내용을 추가하십시오. mytarget 를 프로젝트 이름으로 대체하십시오.
find_package(Qt6 REQUIRED COMPONENTS Multimedia)
target_link_libraries(mytarget PRIVATE Qt6::Multimedia)소스 코드에서 Qt Multimedia 을 빌드하는 방법에 대한 안내는 ‘소스 코드에서 Qt Multimedia 빌드하기’를 참조하십시오.
개요 및 주요 주제
QML 유형
다음 표는 몇 가지 중요한 QML 유형을 요약한 것입니다.
| 유형 | 설명 |
|---|---|
| MediaPlayer | 씬에 오디오/비디오 재생 기능을 추가합니다. |
| CaptureSession | 오디오/비디오 캡처를 위한 세션을 생성합니다. |
| Camera | 시스템에 연결된 카메라에 액세스합니다. |
| AudioInput | 시스템에 연결된 오디오 입력(마이크)에 액세스합니다. |
| AudioOutput | 시스템에 연결된 오디오 출력 장치(스피커, 헤드폰)에 액세스합니다. |
| VideoOutput | 비디오 콘텐츠를 표시합니다. |
| MediaRecorder | CaptureSession 에서 오디오/비디오를 녹화합니다. |
| ImageCapture | 카메라에서 정지 이미지를 캡처합니다. |
| Video | 씬에 비디오 재생 기능을 추가합니다. MediaPlayer 및 VideoOutput 유형을 사용하여 비디오 재생 기능을 제공합니다. |
| ScreenCapture | 화면을 캡처합니다. |
| WindowCapture | 최상위 창을 캡처합니다. |
| GStreamerVideoSource | 사용자 정의 GStreamer 비디오 소스(GStreamer 미디어 백엔드 사용). |
C++ 클래스
다음 표는 몇 가지 중요한 C++ 클래스를 요약한 것입니다.
| 클래스 | 설명 |
|---|---|
| QMediaPlayer | 소스에서 미디어를 재생합니다. |
| QVideoWidget | 미디어 플레이어 또는 캡처 세션의 비디오를 표시합니다. |
| QMediaCaptureSession | 오디오 및 비디오를 캡처합니다. |
| QCamera | 시스템에 연결된 카메라에 액세스합니다. |
| QAudioInput | 시스템에 연결된 오디오 입력(마이크)에 액세스합니다. |
| QAudioOutput | 시스템에 연결된 오디오 출력 장치(스피커, 헤드폰)에 액세스합니다. |
| QImageCapture | 카메라로 정지 이미지를 캡처합니다. |
| QMediaRecorder | 캡처 세션에서 미디어 콘텐츠를 녹화합니다. |
| QVideoSink | 개별 비디오 프레임에 액세스하고 렌더링합니다. |
| QAudioSink | 오디오 출력 장치로 원시 오디오 데이터를 전송합니다. |
| QScreenCapture | 화면을 캡처합니다. |
| QWindowCapture | 최상위 창을 캡처합니다. |
| QVideoFrameInput | 메모리 버퍼의 비디오 프레임을 표시하거나 녹화하는 데 사용됩니다. |
| QAudioBufferInput | 메모리 버퍼에서 오디오를 재생하거나 녹음하는 기능을 지원합니다. |
| QGStreamerVideoSource | 사용자 정의 GStreamer 비디오 소스(GStreamer 미디어 백엔드 사용). |
오디오 및 비디오 재생을 위해 QMediaPlayer, QAudioOutput 및 QVideoWidget 에는 필요한 모든 기능이 포함되어 있습니다. 다른 클래스는 오디오 및 비디오 콘텐츠 캡처 전용이며, QMediaCaptureSession 는 전체 캡처 및 녹화 프로세스를 관리하는 중심 클래스 역할을 합니다.
라이선스 및 출처 표기
Qt Multimedia 모듈은 The Qt Company의 상용 라이선스 하에 제공됩니다. 또한, 이 모듈은 자유 소프트웨어 라이선스 하에서도 사용할 수 있습니다. Qt 5.6부터는 이러한 자유 소프트웨어 라이선스로 GNU Lesser General Public License 버전 3 또는 GNU General Public License 버전 2가 적용됩니다. 자세한 내용은 Qt 라이선싱을 참조하십시오.
또한, Qt 6.12.0의 Qt Multimedia 에는 다음의 관대한 라이선스에 따라 제공되는 타사 모듈이 포함될 수 있습니다:
The Unlicense 또는 MIT No Attribution | |
GNU Lesser General Public License v2.1 이상, BSD 3-Clause "New" 또는 "Revised" 라이선스, BSD 2-Clause "Simplified" 라이선스, BSD Source Code Attribution, ISC 라이선스, MIT 라이선스, Mozilla Public License 2.0 | |
MIT 라이선스 | |
BSD 3조항 "New" 또는 "Revised" 라이선스 | |
Boost 소프트웨어 라이선스 1.0 | |
Independent JPEG Group 라이선스 | |
zlib 라이선스 |
H.264 미디어 압축 표준과 같은 비디오 압축 표준은 특허의 적용을 받을 수 있으며, 이에 따른 로열티 비용이 발생할 수 있습니다. 이는 구현 방식이 운영 체제 서비스로 제공되거나, 타사 라이브러리를 통해 제공되거나, Qt Multimedia 의 백엔드 중 하나로 제공되는 경우를 포함하여 모든 구현에 적용될 수 있습니다. Qt 라이선스는 이러한 비용을 보장하지 않습니다.
대상 플랫폼 및 백엔드 관련 참고 사항
Qt Multimedia 는 미디어 재생, 녹화 및 장치 관리를 위한 사용자 친화적인 크로스 플랫폼 API를 제공합니다. QMediaDevices, QAudioDevice, QSoundEffect, QAudioSink 및 QAudioSource 를 포함한 핵심 API의 구현은 메인 Qt Multimedia 라이브러리에 통합되어 있어 추가 라이브러리가 필요하지 않습니다. 그 외의 Qt Multimedia API는 미디어 백엔드라고 하는 플러그인 라이브러리를 사용하여 구현됩니다. FFmpeg을 기반으로 구축된 주요 미디어 백엔드는 원활한 크로스 플랫폼 기능을 보장하며, WebAssembly 및 임베디드 Linux/Boot2Qt를 제외한 모든 플랫폼에서 기본값으로 설정됩니다. Boot2Qt의 경우 기본 백엔드는 GStreamer를 기반으로 하지만, QT_MEDIA_BACKEND 환경 변수를 사용하여 FFmpeg 미디어 백엔드를 활성화할 수 있습니다.
FFmpeg 백엔드
FFmpeg 미디어 백엔드는 FFmpeg 9.0.1 라이브러리에 의존하며, 이 라이브러리는 Qt Online Installer 에 포함되어 있고 관리자에 의해 테스트를 거쳤습니다. 온라인 설치 프로그램의 바이너리 패키지는 FFmpeg에 대한 동적 링크를 사용합니다. 따라서 애플리케이션은 설치 프로그램에 FFmpeg 바이너리를 포함하거나, 운영 체제에 FFmpeg이 설치되어 있어야 합니다. FFmpeg 라이브러리는 Linux/X11을 제외하고, ‘Qt 애플리케이션 배포’ 문서에 설명된 대로 Qt의 배포 도구를 사용하여 자동으로 배포됩니다. 또한 애플리케이션은 FFmpeg의 주요 버전이 Qt에서 사용하는 버전과 일치하는 경우, 공유 라이브러리나 정적 라이브러리 형태로 자체 빌드한 FFmpeg을 배포할 수도 있습니다.
Qt Multimedia 는 대부분의 운영 체제에서 FFmpeg 미디어 백엔드를 활용하지만, 서로 다른 플랫폼의 애플리케이션 간에는 플랫폼별 기능적 또는 시각적 차이가 발생할 수 있습니다. FFmpeg는 모든 플랫폼에서 동일한 코덱 및 형식 지원을 제공하지 않으며, Qt Multimedia 기능의 성능은 특정 플랫폼에서만 사용 가능한 하드웨어 지원에 따라 달라질 수 있습니다. 예를 들어, FFmpeg는 ARM 아키텍처를 사용하는 Linux 대상 플랫폼에서 하드웨어 가속과 관련하여 특정 문제가 발생합니다. 따라서 Qt Multimedia 애플리케이션을 모든 대상 플랫폼에서 테스트할 것을 권장합니다.
참고: FFmpeg프로젝트는 다양한 라이선스 하에 기능을 제공합니다. 온라인 설치 프로그램을 통해 제공되는 사전 빌드된 FFmpeg 라이브러리에는 ‘라이선스 및 출처 표기’에 나열된 허용적인 라이선스에 부합하는 기능만 포함되어 있습니다.
개발 및 디버깅을 용이하게 하기 위해, 일부 FFmpeg 기능은 비공개 Qt Multimedia API의 일부인 환경 변수를 통해 구성할 수 있습니다.
네이티브 백엔드
기존 애플리케이션과의 호환성을 위해, 각 운영 체제별로 네이티브 미디어 백엔드를 유지하고 있습니다:
- 임베디드 리눅스의GStreamer 백엔드
- macOS 및 iOS용 AVFoundation
- Windows의 Windows Media Foundation (Qt 6.10부터 사용 중단됨)
- Android용 MediaCodec 프레임워크
- WebAssembly의 WebAudio 및 WebVideo
참고: WebAssembly를 제외하고는 FFmpeg 미디어백엔드가 기본 백엔드로 설정되어 있으며, 네이티브 백엔드는 여전히 사용할 수 있지만 지원 범위가 제한적입니다. GStreamer 백엔드는 Linux에서만 사용할 수 있으며, 임베디드 애플리케이션에만 권장됩니다.
참고: Android용MediaCodec은 Qt 6.8부터 사용 중단되었으며, 다음 주요 릴리스에서 제거될 예정입니다.
참고: Windows Media Foundation을 기반으로 구축된 Windows 미디어백엔드는 Qt 6.10부터 사용 중단되었으며, 다음 메이저 릴리스에서 제거될 예정입니다.
Qt 유지보수 팀은 네이티브 백엔드의 중대한 문제를 해결하기 위해 노력하겠지만, 플랫폼 간 동작 불일치를 포함한 사소한 문제의 해결은 보장하지 않습니다. WebAssembly를 제외하고는 새로운 기능은 FFmpeg 미디어 백엔드에서만 구현될 예정입니다.
GStreamer 백엔드에는 보다 세밀한 제어를 가능하게 하는 일부 비공개 API가 있습니다. 그러나 GStreamer 백엔드에는 알려진 버그가 있습니다. 자세한 내용은 GStreamer 백엔드에 대한 플랫폼 참고 사항에서 확인할 수 있습니다.
백엔드의 제한 사항은 문서화될 예정이며, 해당 상태는 각 클래스에서 관리될 것입니다.
백엔드 변경
기본 FFmpeg 백엔드에 문제가 있는 경우, 네이티브 백엔드로 테스트해 볼 것을 권장합니다. QT_MEDIA_BACKEND 환경 변수를 windows, gstreamer (임베디드 리눅스), darwin (macOS 및 iOS), 또는 android 로 설정하여 네이티브 백엔드로 전환할 수 있습니다:
export QT_MEDIA_BACKEND=darwinFFmpeg을 사용될 백엔드로 강제로 지정하려면 변수를 ffmpeg 로 설정하십시오:
export QT_MEDIA_BACKEND=ffmpegQt Multimedia 컴파일 단계에서 기본 미디어 백엔드는 cmake 변수 QT_DEFAULT_MEDIA_BACKEND 을 통해 구성할 수 있습니다.
대상 플랫폼 관련 참고 사항
다음 페이지에는 특정 대상 플랫폼과 관련된 문제점이 나열되어 있습니다.
권한
Qt 6.6부터 Qt Multimedia 모듈은 새로운 QPermission API를 사용하여 camera 및 microphone 권한을 처리합니다. 즉, Qt 자체에서는 더 이상 이러한 권한을 조회하지 않으므로, 클라이언트 애플리케이션에서 직접 이를 처리해야 합니다.
새로운 QPermission API를 애플리케이션에 통합하는 방법에 대한 예제는 ‘애플리케이션 권한’ 페이지를 참조하십시오.
참조 및 예제
© 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.
