Pemutar media

  • Artikel

Pemutaran media melibatkan penayangan dan mendengarkan video dan audio melalui sebaris (disematkan di halaman atau dengan sekelompok kontrol lain) atau pengalaman layar penuh khusus.

Pengguna mengharapkan set kontrol dasar, seperti putar/jeda, lewati kembali, lewati ke depan, yang dapat Anda ubah sesuai kebutuhan (termasuk tombol pemutar media, latar belakang bilah kontrol, dan pengaturan kontrol atau tata letak).

Cuplikan layar elemen pemutar media dengan kontrol transportasi memutar video ladybug

Apakah ini kontrol yang tepat?

Gunakan pemutar media saat Anda ingin memutar audio atau video di aplikasi Anda. Untuk menampilkan kumpulan gambar, gunakan tampilan balik.

Rekomendasi

Pemutar media mendukung tema terang dan gelap, tetapi tema gelap memberikan pengalaman yang lebih baik untuk sebagian besar skenario hiburan. Latar belakang gelap memberikan kontras yang lebih baik, khususnya untuk kondisi cahaya rendah, dan membatasi bilah kontrol agar tidak mengganggu pengalaman menonton.

Saat memutar konten video, dorong pengalaman menonton khusus dengan mempromosikan mode layar penuh melalui mode sebaris. Pengalaman melihat layar penuh optimal, dan opsi dibatasi dalam mode sebaris.

Jika Anda memiliki real estat layar, pergi dengan tata letak baris ganda. Ini menyediakan lebih banyak ruang untuk kontrol daripada tata letak baris tunggal yang ringkas dan dapat lebih mudah dinavigasi menggunakan berbagai input.

Kontrol default telah dioptimalkan untuk pemutaran media, namun Anda memiliki kemampuan untuk menambahkan opsi kustom yang Anda butuhkan ke pemutar media untuk memberikan pengalaman terbaik untuk aplikasi Anda. Kunjungi Membuat kontrol transportasi kustom untuk mempelajari selengkapnya tentang menambahkan kontrol kustom.

UWP dan WinUI 2

Penting

Informasi dan contoh dalam artikel ini dioptimalkan untuk aplikasi yang menggunakan SDK Aplikasi Windows dan WinUI 3, tetapi umumnya berlaku untuk aplikasi UWP yang menggunakan WinUI 2. Lihat referensi API UWP untuk informasi dan contoh spesifik platform.

Bagian ini berisi informasi yang Anda butuhkan untuk menggunakan kontrol di aplikasi UWP atau WinUI 2.

API untuk kontrol ini ada di namespace Windows.UI.Xaml.Controls .

Sebaiknya gunakan WinUI 2 terbaru untuk mendapatkan gaya dan templat terbaru untuk semua kontrol. WinUI 2.2 atau yang lebih baru menyertakan templat baru untuk kontrol ini yang menggunakan sudut bulat. Untuk informasi selengkapnya, lihat Radius sudut.

Jika Anda merancang untuk pengalaman 10 kaki, ikuti tata letak baris ganda. Ini menyediakan lebih banyak ruang untuk kontrol daripada tata letak baris tunggal yang ringkas dan lebih mudah untuk menavigasi menggunakan gamepad untuk 10 kaki. Lihat artikel Merancang untuk Xbox dan TV untuk informasi selengkapnya tentang mengoptimalkan aplikasi Anda untuk pengalaman 10 kaki.

MediaPlayerElementhanya tersedia di Windows 10, versi 1607 dan yang lebih baru. Jika Anda mengembangkan aplikasi untuk versi Windows 10 yang lebih lama, Anda perlu menggunakan kontrol MediaElement sebagai gantinya. Semua rekomendasi yang dibuat di sini juga berlaku untuk MediaElement .

Membuat pemutar media

Buka aplikasi Galeri WinUI 3 dan lihat MediaPlayerElement beraksi.

Aplikasi WinUI 3 Gallery mencakup contoh interaktif sebagian besar kontrol, fitur, dan fungsi WinUI 3. Dapatkan aplikasi dari Microsoft Store atau dapatkan kode sumber di GitHub

Tambahkan media ke aplikasi Anda dengan membuat objek MediaPlayerElement di XAML dan atur Sumber ke MediaSource yang menunjuk ke file audio atau video.

XAML ini membuat MediaPlayerElement dan mengatur properti Sumbernya ke URI file video yang lokal untuk aplikasi. mulai MediaPlayerElement diputar saat halaman dimuat. Untuk menekan media agar tidak segera dimulai, Anda dapat mengatur properti AutoPlay ke false.

<MediaPlayerElement x:Name="mediaPlayerElement"
                    Source="ms-appx:///Videos/video1.mp4"
                    Width="400" AutoPlay="True"/>

XAML ini membuat MediaPlayerElement dengan kontrol transportasi bawaan diaktifkan dan properti AutoPlay diatur ke false.

<MediaPlayerElement x:Name="mediaPlayerElement"
                    Source="ms-appx:///Videos/video1.mp4"
                    Width="400"
                    AutoPlay="False"
                    AreTransportControlsEnabled="True"/>

Penting

Mengatur MediaPlayerElement.Source ke URI relatif (ms-appx/ms-resource) hanya berfungsi dalam aplikasi yang dikemas dengan Proyek Pengemasan Aplikasi Windows. Jika aplikasi Anda tidak menggunakan Proyek Pengemasan Aplikasi Windows, solusi yang disarankan adalah mengonversi URI relatif ms-appx:/// ke URI yang diselesaikan file:/// sepenuhnya. Lihat juga bagian Atur sumber media dan Buka file media lokal nanti di artikel ini.

Kontrol transportasi media

MediaPlayerElement telah dibangun dalam kontrol transportasi yang menangani pemutaran, berhenti, jeda, volume, bisu, pencarian/kemajuan, keterangan tertutup, dan pemilihan trek audio. Untuk mengaktifkan kontrol ini, atur AreTransportControlsEnabled ke true. Untuk menonaktifkannya, atur AreTransportControlsEnabled ke false. Kontrol transportasi diwakili oleh kelas MediaTransportControls . Anda dapat menggunakan kontrol transportasi apa adanya, atau menyesuaikannya dengan berbagai cara. Untuk informasi selengkapnya, lihat referensi kelas MediaTransportControls dan Membuat kontrol transportasi kustom.

Kontrol transportasi mendukung tata letak baris tunggal dan ganda. Contoh pertama di sini adalah tata letak baris tunggal, dengan tombol putar/jeda yang terletak di sebelah kiri garis waktu media. Tata letak ini paling baik disediakan untuk pemutaran media sebaris dan layar ringkas.

Contoh kontrol MTC, baris tunggal

Tata letak kontrol baris ganda (di bawah) direkomendasikan untuk sebagian besar skenario penggunaan, terutama pada layar yang lebih besar. Tata letak ini menyediakan lebih banyak ruang untuk kontrol dan membuat garis waktu lebih mudah bagi pengguna untuk beroperasi.

Contoh kontrol MTC, baris ganda

Kontrol transportasi media sistem

MediaPlayerElement secara otomatis terintegrasi dengan kontrol transportasi media sistem. Kontrol transportasi media sistem adalah kontrol yang muncul ketika tombol media perangkat keras ditekan, seperti tombol media pada keyboard. Untuk informasi selengkapnya, lihat SystemMediaTransportControls.

Mengatur sumber media

Untuk memutar file di jaringan atau file yang disematkan dengan aplikasi, atur properti Sumber ke MediaSource dengan jalur file.

Tip

Untuk membuka file dari internet, Anda perlu mendeklarasikan kemampuan Internet (Klien) dalam manifes aplikasi Anda (Package.appxmanifest). Untuk informasi selengkapnya tentang mendeklarasikan kemampuan, lihat Deklarasi kemampuan aplikasi.

Kode ini mencoba mengatur properti Sumber dari MediaPlayerElement yang ditentukan dalam XAML ke jalur file yang dimasukkan ke dalam TextBox.

<TextBox x:Name="txtFilePath" Width="400"
         FontSize="20"
         KeyUp="TxtFilePath_KeyUp"
         Header="File path"
         PlaceholderText="Enter file path"/>

private void TxtFilePath_KeyUp(object sender, KeyRoutedEventArgs e)
{
    if (e.Key == Windows.System.VirtualKey.Enter)
    {
        TextBox tbPath = sender as TextBox;

        if (tbPath != null)
        {
            LoadMediaFromString(tbPath.Text);
        }
    }
}

private void LoadMediaFromString(string path)
{
    try
    {
        Uri pathUri = new Uri(path);
        mediaPlayerElement.Source = MediaSource.CreateFromUri(pathUri);
    }
    catch (Exception ex)
    {
        if (ex is FormatException)
        {
            // handle exception.
            // For example: Log error or notify user problem with file
        }
    }
}

Untuk mengatur sumber media ke file media yang disematkan di aplikasi, inisialisasi Uri dengan jalur yang diawali dengan ms-appx:///, buat MediaSource dengan Uri lalu atur Sumber ke Uri. Misalnya, untuk file yang disebut video1.mp4 yang ada di subfolder Video , jalurnya akan terlihat seperti: ms-appx:///Videos/video1.mp4

Penting

Mengatur MediaPlayerElement.Source ke URI relatif (ms-appx/ms-resource) hanya berfungsi dalam aplikasi yang dikemas dengan Proyek Pengemasan Aplikasi Windows.

Kode ini mengatur properti Sumber dari MediaPlayerElement yang ditentukan sebelumnya di XAML ke ms-appx:///Videos/video1.mp4.

private void LoadEmbeddedAppFile()
{
    try
    {
        Uri pathUri = new Uri("ms-appx:///Videos/video1.mp4");
        mediaPlayerElement.Source = MediaSource.CreateFromUri(pathUri);
    }
    catch (Exception ex)
    {
        if (ex is FormatException)
        {
            // handle exception.
            // For example: Log error or notify user problem with file
        }
    }
}

Buka file media lokal

Untuk membuka file di sistem lokal atau dari OneDrive, Anda bisa menggunakan FileOpenPicker untuk mendapatkan file dan Sumber untuk mengatur sumber media, atau Anda dapat mengakses folder media pengguna secara terprogram.

Jika aplikasi Anda memerlukan akses tanpa interaksi pengguna ke folder Musik atau Video , misalnya, jika Anda menghitung semua file musik atau video dalam koleksi pengguna dan menampilkannya di aplikasi Anda, maka Anda perlu mendeklarasikan kemampuan Perpustakaan Musik dan Perpustakaan Video . Untuk informasi selengkapnya, lihat File dan folder di pustaka Musik, Gambar, dan Video.

FileOpenPicker tidak memerlukan kemampuan khusus untuk mengakses file pada sistem file lokal, seperti folder Musik atau Video pengguna, karena pengguna memiliki kontrol penuh atas file mana yang sedang diakses. Dari sudut depan keamanan dan privasi, yang terbaik adalah meminimalkan jumlah kemampuan yang digunakan aplikasi Anda.

Untuk membuka media lokal menggunakan FileOpenPicker

  1. Panggil FileOpenPicker untuk mengizinkan pengguna memilih file media.

    Gunakan kelas FileOpenPicker untuk memilih file media. Atur FileTypeFilter untuk menentukan tipe file mana yang FileOpenPicker ditampilkan. Panggil PickSingleFileAsync untuk meluncurkan pemilih file dan mendapatkan file.

  2. Gunakan MediaSource untuk mengatur file media yang dipilih sebagai MediaPlayerElement.Source.

    Untuk menggunakan StorageFile yang dikembalikan dari FileOpenPicker, Anda perlu memanggil metode CreateFromStorageFile di MediaSource dan mengaturnya sebagai SumberMediaPlayerElement. Kemudian panggil Putar di MediaPlayerElement.MediaPlayer untuk memulai media.

Contoh ini menunjukkan cara menggunakan FileOpenPicker untuk memilih file dan mengatur file sebagai SumberMediaPlayerElement.

<MediaPlayerElement x:Name="mediaPlayerElement"/>
...
<Button Content="Choose file" Click="Button_Click"/>

private async void Button_Click(object sender, RoutedEventArgs e)
{
    await SetLocalMedia();
}

async private System.Threading.Tasks.Task SetLocalMedia()
{
    var openPicker = new Windows.Storage.Pickers.FileOpenPicker();
    WinRT.Interop.InitializeWithWindow.Initialize(openPicker, WinRT.Interop.WindowNative.GetWindowHandle(this));

    openPicker.FileTypeFilter.Add(".wmv");
    openPicker.FileTypeFilter.Add(".mp4");
    openPicker.FileTypeFilter.Add(".wma");
    openPicker.FileTypeFilter.Add(".mp3");

    var file = await openPicker.PickSingleFileAsync();

    // mediaPlayerElement is a MediaPlayerElement control defined in XAML
    if (file != null)
    {
        mediaPlayerElement.Source = MediaSource.CreateFromStorageFile(file);

        mediaPlayerElement.MediaPlayer.Play();
    }
}

Mengatur sumber poster

Anda dapat menggunakan properti PosterSource untuk menyediakan representasi visual mediaPlayerElement sebelum media dimuat. PosterSource adalah gambar, seperti cuplikan layar, poster film, atau seni album, yang ditampilkan sebagai pengganti media. PosterSource ditampilkan dalam situasi berikut:

  • Ketika sumber yang valid tidak diatur. Misalnya, Sumber tidak diatur, Source diatur ke null, atau sumber tidak valid (seperti halnya ketika peristiwa MediaFailed terjadi).
  • Saat media sedang dimuat. Misalnya, sumber yang valid diatur, tetapi peristiwa MediaOpened belum terjadi.
  • Ketika media mengalir ke perangkat lain.
  • Ketika media hanya audio.

Berikut adalah MediaPlayerElement dengan Sumbernya diatur ke trek album, dan PosterSource diatur ke gambar sampul album.

<MediaPlayerElement Source="ms-appx:///Media/Track1.mp4" PosterSource="ms-appx:///Media/AlbumCover.png"/>

Jaga agar layar perangkat tetap aktif

Biasanya, perangkat meredupkan layar (dan akhirnya mematikannya) untuk menghemat masa pakai baterai saat pengguna tidak aktif, tetapi aplikasi video perlu mengaktifkan layar sehingga pengguna dapat melihat video. Untuk mencegah tampilan dinonaktifkan saat tindakan pengguna tidak lagi terdeteksi, seperti saat aplikasi memutar video, Anda dapat memanggil DisplayRequest.RequestActive. Kelas DisplayRequest memungkinkan Anda memberi tahu Windows untuk mengaktifkan tampilan sehingga pengguna dapat melihat video.

Untuk menghemat daya dan masa pakai baterai, Anda harus memanggil DisplayRequest.RequestRelease untuk melepaskan permintaan tampilan saat tidak lagi diperlukan. Windows secara otomatis menonaktifkan permintaan tampilan aktif aplikasi Anda saat aplikasi Anda berpindah dari layar, dan mengaktifkannya kembali saat aplikasi Kembali ke latar depan.

Berikut adalah beberapa situasi ketika Anda harus merilis permintaan tampilan:

  • Pemutaran video dijeda, misalnya, oleh tindakan pengguna, buffering, atau penyesuaian karena bandwidth terbatas.
  • Pemutaran berhenti. Misalnya, video selesai diputar atau presentasi selesai.
  • Terjadi kesalahan pemutaran. Misalnya, masalah konektivitas jaringan atau file yang rusak.

Agar layar tetap aktif

  1. Buat variabel DisplayRequest global. Inisialisasi ke null.

    private DisplayRequest appDisplayRequest = null;

  2. Panggil RequestActive untuk memberi tahu Windows bahwa aplikasi mengharuskan tampilan tetap aktif.

  3. Panggil RequestRelease untuk merilis permintaan tampilan setiap kali pemutaran video dihentikan, dijeda, atau terganggu oleh kesalahan pemutaran. Ketika aplikasi Anda tidak lagi memiliki permintaan tampilan aktif, Windows menghemat masa pakai baterai dengan meredupkan layar (dan akhirnya mematikannya) saat perangkat tidak digunakan.

Setiap MediaPlayerElement.MediaPlayer memiliki PlaybackSession jenis MediaPlaybackSession yang mengontrol berbagai aspek pemutaran media seperti PlaybackRate, PlaybackState , dan Posisi. Di sini, Anda menggunakan peristiwa PlaybackStateChanged di MediaPlayer.PlaybackSession untuk mendeteksi situasi saat Anda harus merilis permintaan tampilan. Kemudian, gunakan properti NaturalVideoHeight untuk menentukan apakah file audio atau video diputar, dan jaga layar tetap aktif hanya jika video diputar.

<MediaPlayerElement x:Name="mediaPlayerElement" Source="ms-appx:///Videos/video1.mp4"/>

public sealed partial class MainWindow : Window
{
    public DisplayRequest appDisplayRequest = null;
    // using Microsoft.UI.Dispatching;
    private DispatcherQueue dispatcherQueue = DispatcherQueue.GetForCurrentThread();

    public MainWindow()
    {
        this.InitializeComponent();
        mediaPlayerElement.MediaPlayer.PlaybackSession.PlaybackStateChanged += 
            PlaybackSession_PlaybackStateChanged;
    }

    private void PlaybackSession_PlaybackStateChanged(MediaPlaybackSession sender, object args)
    {
        MediaPlaybackSession playbackSession = sender as MediaPlaybackSession;
        if (playbackSession != null && playbackSession.NaturalVideoHeight != 0)
        {
            if (playbackSession.PlaybackState == MediaPlaybackState.Playing)
            {
                if (appDisplayRequest is null)
                {
                    dispatcherQueue.TryEnqueue(DispatcherQueuePriority.Normal, () =>
                    {
                        appDisplayRequest = new DisplayRequest();
                        appDisplayRequest.RequestActive();
                    });
                }
            }
            else // PlaybackState is Buffering, None, Opening, or Paused.
            {
                if (appDisplayRequest is not null)
                {
                    appDisplayRequest.RequestRelease();
                    appDisplayRequest = null;
                }
            }
        }
    }
}

Mengontrol pemutar media secara terprogram

MediaPlayerElement menyediakan banyak properti, metode, dan peristiwa untuk mengontrol pemutaran audio dan video melalui properti MediaPlayerElement.MediaPlayer . Untuk daftar lengkap properti, metode, dan peristiwa, lihat halaman referensi MediaPlayer .

Skenario pemutaran media tingkat lanjut

Untuk skenario pemutaran media yang lebih kompleks seperti memutar daftar putar, beralih antar bahasa audio, atau membuat trek metadata kustom, atur MediaPlayerElement.Source ke MediaPlaybackItem atau MediaPlaybackList. Lihat halaman Pemutaran media untuk informasi selengkapnya tentang cara mengaktifkan berbagai fungsionalitas media tingkat lanjut.

Mengubah ukuran dan meregangkan video

Gunakan properti Stretch untuk mengubah cara konten video dan/atau PosterSource mengisi kontainer tempatnya berada. Ini mengubah ukuran dan meregangkan video tergantung pada nilai Stretch . Statusnya Stretch mirip dengan pengaturan ukuran gambar di banyak set TV. Anda dapat menghubungkan ini ke tombol dan memungkinkan pengguna untuk memilih pengaturan mana yang mereka sukai.

  • Tidak ada yang menampilkan resolusi asli konten dalam ukuran aslinya. Hal ini dapat mengakibatkan beberapa video dipotong atau bilah hitam di tepi video.
  • Seragam mengisi ruang sebanyak mungkin sambil mempertahankan rasio aspek dan konten video. Ini dapat mengakibatkan bilah hitam horizontal atau vertikal di tepi video. Ini mirip dengan mode layar lebar.
  • UniformToFill mengisi seluruh ruang sambil mempertahankan rasio aspek. Ini dapat mengakibatkan beberapa video dipangkas. Ini mirip dengan mode layar penuh.
  • Isi mengisi seluruh ruang, tetapi tidak mempertahankan rasio aspek. Tidak ada video yang dipangkas, tetapi peregangan dapat terjadi. Ini mirip dengan mode stretch.

Meregangkan nilai enumerasi

Di sini, AppBarButton digunakan untuk menelusuri opsi Stretch . Pernyataan switch memeriksa status properti Stretch saat ini dan mengaturnya ke nilai berikutnya dalam Stretch enumerasi. Ini memungkinkan pengguna menelusuri berbagai status peregangan.

<AppBarButton Icon="Trim"
              Label="Resize Video"
              Click="PictureSize_Click" />

private void PictureSize_Click(object sender, RoutedEventArgs e)
{
    switch (mediaPlayerElement.Stretch)
    {
        case Stretch.Fill:
            mediaPlayerElement.Stretch = Stretch.None;
            break;
        case Stretch.None:
            mediaPlayerElement.Stretch = Stretch.Uniform;
            break;
        case Stretch.Uniform:
            mediaPlayerElement.Stretch = Stretch.UniformToFill;
            break;
        case Stretch.UniformToFill:
            mediaPlayerElement.Stretch = Stretch.Fill;
            break;
        default:
            break;
    }
}

Aktifkan pemutaran latensi rendah

Atur properti RealTimePlayback ke true di MediaPlayerElement.MediaPlayer untuk mengaktifkan elemen pemutar media guna mengurangi latensi awal untuk pemutaran. Ini sangat penting untuk aplikasi komunikasi dua arah, dan dapat berlaku untuk beberapa skenario game. Ketahuilah bahwa mode ini lebih intensif sumber daya dan kurang hemat daya.

Contoh ini membuat MediaPlayerElement dan mengatur RealTimePlayback ke true.

MediaPlayerElement mediaPlayerElement = new MediaPlayerElement();
mediaPlayerElement.MediaPlayer.RealTimePlayback = true;