Back to Qt.io
Contact Us Blog Download Qt
이 페이지에서

QML 미디어 플레이어 예제

QML MediaPlayer 타입을 사용하여 오디오 및 비디오 재생하기.

재생 제어 기능과 동영상 미리보기 영역이 표시된 동영상 플레이어

이 예제는 다양한 코덱을 사용하여 오디오 및 비디오 파일을 재생할 수 있는 간단한 멀티미디어 플레이어를 보여줍니다.

예제 실행

다음 위치에서 예제를 실행할 수 있습니다.

MediaPlayer 인스턴스 생성

이 예제의 QML 코드 진입점은 Main.qml 입니다. 여기서는 ApplicationWindow 가 생성되고, id, title, width, height 와 같은 속성이 설정됩니다.

ApplicationWindow {
    id: root
    title: qsTr("Multimedia Player")
    width: 1280
    height: 720

다음으로 ` MediaPlayer `를 생성하고, 비디오 및 오디오 출력을 담당하는 두 가지 속성을 정의합니다. 첫째, 비디오 뷰파인더를 렌더링하는 ` videoOutput `이고, 둘째, 플레이어의 오디오 출력을 제공하는 ` audioOutput `입니다.

MediaPlayer {
    id: mediaPlayer
    ...
videoOutput: videoOutput
audioOutput: AudioOutput {
    id: audio
    muted: playbackController.muted
    volume: playbackController.volume
}
    ...
VideoOutput {
    id: videoOutput
    anchors.fill: parent
    visible: mediaPlayer.mediaStatus > 0

    TapHandler {
        onDoubleTapped: {
            root.fullScreen ?  root.showNormal() : root.showFullScreen()
            root.fullScreen = !root.fullScreen
        }
    }
}

VideoOutput 유형의 visible 속성은 MediaPlayer 의 mediaStatus 속성이 0보다 클 때 true 로 설정됩니다. mediaStatus 는 열거형이며, 미디어가 설정되지 않았을 때는 0이고, 그 외의 경우에는 0보다 큽니다. 따라서 미디어가 설정되었을 때 VideoOutput 가 표시됩니다.

MediaPlayer 유형에는 오류를 처리하기 위해 특별히 재정의할 수 있는 onErrorOccurred 라는 신호 속성이 있습니다. 이 경우 해당 신호는 open() 메서드를 사용하여 MessageDialog 를 열고, 그 text 속성을 MediaPlayer 속성인 errorString 로 설정합니다.

onErrorOccurred: {
    mediaError.text = mediaPlayer.errorString
    mediaError.open()
}

재생 컨트롤

실용적인 미디어 플레이어를 구현하려면 재생을 제어할 수 있는 인터페이스가 필요합니다. 이 인터페이스는 별도의 컴포넌트 파일인 PlaybackControl.qml 에서 생성되며, Main.qml 에서 인스턴스화됩니다.

PlaybackControl {
    id: playbackController
    ...
onTracksChanged: {
    audioTracksInfo.read(mediaPlayer.audioTracks)
    videoTracksInfo.read(mediaPlayer.videoTracks)
    subtitleTracksInfo.read(mediaPlayer.subtitleTracks, 6) /* QMediaMetaData::Language = 6 */
    updateMetadata()
    mediaPlayer.play()
}

생성 시, 트랙 정보, 메타데이터 정보 및 ` MediaPlayer ` 객체 자체와 같은 객체들이 이 유형으로 전달됩니다. ` PlaybackControl.qml`에서 이러한 각 객체는 ` required property`을 가지며, 이는 ` PlaybackControl ` 객체가 생성될 때 이러한 속성을 설정해야 함을 의미합니다.

Item {
    id: playbackController

    required property MediaPlayer mediaPlayer
    required property MetadataInfo metadataInfo
    required property TracksInfo audioTracksInfo
    required property TracksInfo videoTracksInfo
    required property TracksInfo subtitleTracksInfo

이러한 재생 제어 기능은 여러 섹션으로 나눌 수 있습니다. 패널의 왼쪽 상단에는 파일 탐색기에서 파일을 선택하거나 URL을 입력하여 파일을 여는 데 사용되는 버튼 모음이 있습니다. 파일은 source 속성을 설정하여 MediaPlayer 에 로드됩니다. 두 버튼 모두 CustomButton custom component 을 사용하여 인스턴스화됩니다.

CustomButton {
    id: fileDialogButton
    icon.source: "../images/open_new.svg"
    flat: false
    onClicked: fileDialog.open()
}

CustomButton {
    id: openUrlButton
    icon.source: "../images/link.svg"
    flat: false
    onClicked: urlPopup.open()
}

세 개의 버튼이 생성되어 이 패널의 중앙에 배치되며, 재생, 일시 정지, 10초 앞뒤로 이동 기능을 처리합니다. 미디어는 각각 play() 및 pause() 메서드를 사용하여 재생 및 일시 정지됩니다. 재생 또는 일시 정지 버튼을 언제 그려야 할지 알기 위해 playbackState 속성을 조회합니다. 예를 들어, 이 속성이 열거형 값 MediaPlayer.PlayingState 와 같을 때 일시 정지 버튼이 그려집니다.

CustomRoundButton {
    id: playButton
    visible: playbackController.mediaPlayer.playbackState !== MediaPlayer.PlayingState
    icon.source: "../images/play_symbol.svg"
    onClicked: playbackController.mediaPlayer.play()
}

CustomRoundButton {
    id: pauseButton
    visible: playbackController.mediaPlayer.playbackState === MediaPlayer.PlayingState
    icon.source: "../images/pause_symbol.svg"
    onClicked: playbackController.mediaPlayer.pause()
}

10초 앞으로 또는 뒤로 이동하려면, MediaPlayer 유형의 position 값을 10,000 밀리초만큼 증가시킨 후 setPosition() 메서드를 사용하여 설정합니다.

CustomRoundButton {
    id: forward10Button
    icon.source: "../images/forward10.svg"
    onClicked: {
        const pos = Math.min(playbackController.mediaPlayer.duration,
                           playbackController.mediaPlayer.position + 10000)
        playbackController.mediaPlayer.setPosition(pos)
    }
}

재생 탐색 및 오디오

PlaybackControl.qml 에서는 AudioControl 및 PlaybackSeekControl 유형이 인스턴스화됩니다. 이 둘은 각각 별도의 컴포넌트 파일에 정의되어 있으며, 각각 볼륨 제어와 재생 위치를 이동하는 기능을 담당합니다. AudioControl 유형은 음소거 버튼과 플레이어의 볼륨을 설정하기 위한 QtQuick Controls 의 Slider 를 정의합니다. 이 두 속성은 mute 및 volume 속성을 정의하여 노출되며, Main.qml 의 AudioOutput 정의에서 액세스할 수 있습니다.

property alias muted: muteButton.checked
property real volume: slider.value

PlaybackSeekControl 는 RowLayout 를 사용하며, 여기에는 Slider 가 포함되어 있고 양쪽에 Text 항목이 배치되어 있습니다. 두 개의 Text 항목은 재생 중인 미디어의 현재 시간과 남은 시간을 표시합니다. 이 두 값은 MediaPlayer 유형의 두 속성, 즉 현재 재생 위치를 밀리초 단위로 제공하는 position 와 미디어의 재생 시간을 밀리초 단위로 제공하는 duration 를 사용하여 계산됩니다.

Label {
    id: currentTime
    Layout.preferredWidth: 45
    text: seekController.formatToMinutes(seekController.mediaPlayer.position)
    horizontalAlignment: Text.AlignLeft
    font.pixelSize: 11
}
    ...
Label {
    id: remainingTime
    Layout.preferredWidth: 45
    text: seekController.formatToMinutes(seekController.mediaPlayer.duration - seekController.mediaPlayer.position)
    horizontalAlignment: Text.AlignRight
    font.pixelSize: 11
}

Slider 는 미디어 플레이어가 탐색이 가능한 경우에만 활성화되며, 예를 들어 라이브 미디어의 경우에는 활성화되지 않습니다. MediaPlayer 유형에는 이를 위한 seekable 라는 속성이 있습니다. Slider 의 value 는 MediaPlayer 의 position 및 duration 속성을 사용하여 계산됩니다.

enabled: seekController.mediaPlayer.seekable
value: seekController.mediaPlayer.position / seekController.mediaPlayer.duration

메타데이터 및 트랙 정보

PlaybackControl 타입은 SettingsPopup 의 인스턴스를 생성하며, 이 객체에는 현재 로드된 미디어 및 트랙 선택에 대한 메타데이터 정보와 재생 속도 업데이트 기능이 포함되어 있습니다. 이 Popup 는 SettingsPopup.qml 에서 정의됩니다.

사용자가 선택할 수 있는 재생 설정 및 메타데이터 정보

메타데이터는 별도의 구성 요소 파일인 MetadataInfo.qml 에 포함되어 있습니다. 이 파일에는 ` ListModel`, 이를 지우는 함수인 ` clear()`, 그리고 메타데이터를 채우는 함수인 ` read(MediaMetadata metadata)`가 포함되어 있습니다. read(MediaMetadata metadata) 함수는 MediaMetaData 유형의 객체를 매개변수로 받아, 해당 키-값 구조를 탐색하여 데이터를 ListView 의 model 로 추출합니다. 이를 수행하는 데 사용되는 메서드는 MediaMetaData 의 모든 키를 반환하는 keys() 와, 주어진 key 에 대한 value 를 반환하는 {stringValue(Key key)}입니다.

function read(metadata) {
    if (!metadata)
        return
    for (const key of metadata.keys())
        if (metadata.stringValue(key))
            listModel.append({
                                name: metadata.metaDataKeyToString(key),
                                value: metadata.stringValue(key)
                            })
}

ListModel {
    id: listModel
}

그런 다음 데이터는 SettingsPopup.qml 에서 ListView 유형으로 표시됩니다. 이 ListView 의 delegate 는 MediaMetaData 항목에서 추상화된 키-값 쌍에 해당하는 두 개의 Text 항목으로 구성된 행입니다.

Popup 의 반대편에는 오디오, 비디오 및 자막에 대한 재생 속도 제어 및 트랙 선택 기능이 있습니다. 재생 속도는 ComboBox 에서 선택되며, playbackRate 속성을 사용하여 설정됩니다.

settingsController.mediaPlayer.playbackRate = (currentIndex + 1) * 0.25

TracksInfo.qml 에 정의된 TracksInfo 라는 타입은 트랙에 대한 데이터를 포함합니다. 더 구체적으로 말하면, 트랙의 제목이나(자막의 경우 특히) 언어를 포함하는 ListModel 입니다. 이 정보는 TracksInfo 타입에 정의된 read(MediaMetadata mediaMetadata) 함수를 호출하여 Main.qml 에 채워집니다.

onTracksChanged: {
    audioTracksInfo.read(mediaPlayer.audioTracks)
    videoTracksInfo.read(mediaPlayer.videoTracks)
    subtitleTracksInfo.read(mediaPlayer.subtitleTracks, 6) /* QMediaMetaData::Language = 6 */
    updateMetadata()
    mediaPlayer.play()
}

그런 다음 TracksInfo 에 정의된 model 를 SettingsPopup 의 ComboBox에서 조회하여 현재 트랙을 선택합니다.

settingsController.mediaPlayer.pause()
tracksInfo.selectedTrack = currentIndex
settingsController.mediaPlayer.play()

예제 프로젝트 @ code.qt.io

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