Pemutar media

Pemutaran media melibatkan tampilan 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 media player, latar belakang bilah kontrol, dan pengaturan atau tata letak kontrol).

Apakah ini kontrol yang tepat?

Gunakan media player saat Anda ingin memutar audio atau video di aplikasi Anda. Untuk menampilkan kumpulan gambar, gunakan flip view.

Recommendations

media player 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 daripada mode inline. Pengalaman tampilan layar penuh optimal, dan opsi dibatasi dalam mode sebaris.

Jika Anda memiliki ruang layar, gunakan 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 media player untuk memberikan pengalaman terbaik untuk aplikasi Anda. Kunjungi Membuat kontrol transportasi kustom untuk mempelajari lebih lanjut tentang cara menambahkan kontrol kustom.

Membuat media player

• API Penting: Kelas MediaPlayerElement, Kelas MediaTransportControls

Buka aplikasi Galeri WinUI 3 dan lihat MediaPlayerElement sedang beraksi

Aplikasi Galeri WinUI 3 mencakup contoh interaktif kontrol dan fitur WinUI. Dapatkan aplikasi dari Microsoft Store atau telusuri kode sumber pada 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 Sumber ke URI file video yang terdapat secara lokal dalam aplikasi. MediaPlayerElement mulai diputar ketika 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 transport bawaan yang 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 Kemasan Aplikasi Windows. Jika aplikasi Anda tidak menggunakan Proyek Kemasan Aplikasi Windows, solusi yang direkomendasikan adalah mengonversi URI relatif ms-appx:/// ke URI file:/// yang diselesaikan sepenuhnya. Lihat juga bagian Atur sumber media dan Buka file media lokal nanti di artikel ini.

Kontrol transportasi media

MediaPlayerElement memiliki kontrol transport yang menangani pemutaran, berhenti, jeda, volume, bisu, pencarian/progres, 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 digunakan untuk pemutaran media se-baris dan layar kecil.

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.

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.

Petunjuk / Saran

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 Kemasan Aplikasi Windows.

Kode ini mengatur properti Source dari MediaPlayerElement yang telah didefinisikan sebelumnya dalam 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 pada sistem lokal atau dari OneDrive, Anda dapat menggunakan FileOpenPicker untuk mendapatkan file dan Source 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 pada 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 keamanan dan privasi, yang terbaik adalah meminimalkan jumlah kemampuan yang digunakan aplikasi Anda.

Untuk membuka media lokal menggunakan FileOpenPicker

1. Panggil FileOpenPicker untuk membiarkan 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 pada MediaSource dan mengaturnya sebagai Source dari MediaPlayerElement. Kemudian panggil Putar di MediaPlayerElement.MediaPlayer untuk memulai media.

Contoh ini menunjukkan cara menggunakan FileOpenPicker untuk memilih file dan mengatur file sebagai Source dari MediaPlayerElement.

<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 Anda sebelum media dimuat. Sebuah PosterSource adalah gambar, seperti cuplikan layar, poster film, atau sampul album, yang ditampilkan untuk menggantikan media. PosterSource ditampilkan dalam situasi berikut:

• Ketika sumber yang valid belum 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 ditetapkan, tetapi MediaOpened event belum terjadi.
• Ketika media sedang streaming ke perangkat lain.
• Ketika media hanya audio.

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

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

Menjaga layar perangkat tetap aktif

Biasanya, perangkat meredupkan layar (dan akhirnya mematikannya) untuk menghemat masa pakai baterai saat pengguna pergi, tetapi aplikasi video perlu menjaga layar tetap aktif 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 merilis 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, berdasarkan 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.

Untuk menjaga layar tetap aktif

1. Buat variabel DisplayRequest global. Inisialisasi itu 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. Saat 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 kapan 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 media player 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 tempat konten tersebut 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. 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 dipotong. Ini mirip dengan mode layar penuh.
• Isi mengisi seluruh ruang, tetapi tidak mempertahankan rasio aspek. Tidak ada bagian dari video yang dipotong, tetapi peregangan dapat terjadi. Ini mirip dengan mode stretch.

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 pada MediaPlayerElement.MediaPlayer untuk mengaktifkan elemen media player 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;

Artikel terkait

• Dasar-dasar desain perintah untuk aplikasi Windows
• Dasar-dasar desain konten untuk aplikasi Windows