MediaElement

MediaElement 는 비디오 및 오디오 재생을 위한 컨트롤입니다. 기본 플랫폼에서 지원하는 미디어는 다음 원본에서 재생할 수 있습니다.

• URI(HTTP 또는 HTTPS)를 사용하는 웹입니다.
• URI 체계를 사용하여 플랫폼 애플리케이션에 embed:// 포함된 리소스입니다.
• URI 체계를 사용하여 filesystem:// 앱의 로컬 파일 시스템에 있는 파일입니다.

MediaElement 는 전송 컨트롤이라고 하는 플랫폼 재생 컨트롤을 사용할 수 있습니다. 그러나 기본적으로 사용하지 않도록 설정되며 사용자 고유의 전송 컨트롤로 바꿀 수 있습니다. 다음 스크린샷은 플랫폼 전송 컨트롤을 사용하여 비디오를 재생하는 것을 보여 MediaElement 줍니다.

다음 MediaElement 플랫폼 구현을 사용합니다.

시작

.NET MAUI 커뮤니티 도구 키트의 기능을 사용 MediaElement 하려면 다음 단계가 필요합니다.

NuGet 패키지 설치

애플리케이션 내에서 사용하기 MediaElement 전에 NuGet 패키지를 설치 CommunityToolkit.Maui.MediaElement 하고 MauiProgram.cs 초기화 줄을 추가해야 합니다. 다음과 같습니다.

패키지 이름: CommunityToolkit.Maui.MediaElement

패키지 URL:https://www.nuget.org/packages/CommunityToolkit.Maui.MediaElement

패키지 초기화

먼저 using 문을 MauiProgram.cs 파일의 맨 위에 추가해야 합니다.

using CommunityToolkit.Maui.MediaElement;

올바르게 사용 MediaElement 하려면 애플리케이션을 UseMauiCommunityToolkitMediaElement 부트스트래핑할 때 클래스에서 MauiAppBuilder 메서드를 호출해야 MauiProgram.cs. 다음 예제에서는 이 작업을 수행하는 방법을 보여줍니다.

var builder = MauiApp.CreateBuilder();
builder
    .UseMauiApp<App>()
    .UseMauiCommunityToolkitMediaElement()

이 작업을 수행하는 방법에 대한 자세한 내용은 시작 페이지를 참조하세요.

플랫폼별 초기화

기능에 액세스 MediaElement 하려면 다음 플랫폼별 설정이 필요합니다.

[Activity(Theme = "@style/Maui.SplashTheme", ResizeableActivity = true, MainLauncher = true, LaunchMode = LaunchMode.SingleTask)]
public class MainActivity : MauiAppCompatActivity
{
}

 <service android:name="communityToolkit.maui.media.services" android:stopWithTask="true" android:exported="false" android:enabled="true" android:foregroundServiceType="mediaPlayback">
   <intent-filter>
     <action android:name="androidx.media3.session.MediaSessionService"/>
   </intent-filter>
 </service>

<SupportedOSPlatformVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'android'">26.0</SupportedOSPlatformVersion>

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />
<uses-permission android:name="android.permission.MEDIA_CONTENT_CONTROL" />

<service android:name="communityToolkit.maui.media.services" android:stopWithTask="true" android:exported="false" android:enabled="true" android:foregroundServiceType="mediaPlayback">
    <intent-filter>
        <action android:name="androidx.media3.session.MediaSessionService"/>
    </intent-filter>
</service>
</application>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.FOREGROUND_SERVICE"/>
<uses-permission android:name="android.permission.POST_NOTIFICATIONS"/>
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK"/>
<uses-permission android:name="android.permission.MEDIA_CONTENT_CONTROL"/>

<key>UIBackgroundModes</key>
<array>
    <string>bluetooth-central</string>
    <string>audio</string>
</array>
<key>NSLocalNetworkUsageDescription</key>
<string></string>

<key>UIBackgroundModes</key>
<array>
    <string>audio</string>
</array>

지원되는 형식

지원되는 멀티미디어 형식은 플랫폼별로 다를 수 있습니다. 경우에 따라 앱을 실행하는 동안 사용 가능한 디코더 또는 운영 체제에 설치된 디코더에 따라 달라질 수도 있습니다. 각 플랫폼에서 지원되는 형식에 대한 자세한 내용은 아래 링크를 참조하세요.

일반적인 시나리오

다음 섹션에서는 .에 대한 일반적인 사용 시나리오를 다룹니다 MediaElement.

원격 미디어 재생

A는 MediaElement HTTP 및 HTTPS URI 스키마를 사용하여 원격 미디어 파일을 재생할 수 있습니다. 이 작업은 속성을 미디어 파일의 URI로 설정 Source 하여 수행됩니다.

<toolkit:MediaElement Source="https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4"
              ShouldShowPlaybackControls="True" />

기본적으로 속성에 의해 Source 정의된 미디어는 미디어가 열린 후 즉시 재생을 시작하지 않습니다. 자동 미디어 재생을 사용하려면 속성을 ShouldAutoPlay.로 설정합니다true.

플랫폼 제공 미디어 재생 컨트롤은 기본적으로 사용하도록 설정되며 속성을 ShouldShowPlaybackControls.로 설정하여 사용하지 않도록 설정할 false 수 있습니다.

메타데이터 사용

A는 MediaElement 및 MediaElement.MetadataTitleMediaElement.MetadataArtist.에 대한 메타데이터를 MediaElement.MetadataArtworkUrl사용할 수 있습니다. 타이틀 또는 아티스트를 설정하여 Windows, Mac Catalyst, iOS 및 Android용 잠금 화면 컨트롤에서 현재 재생 중인 내용을 표시할 수 있습니다. 잠금 화면의 아트워크를 사용하여 로컬 또는 원격 URL 설정할 수 있습니다. 최상의 품질을 표시하려면 1080P 이상이어야 합니다. URL이어야 하며 .jpg.png

<toolkit:MediaElement 
    MetadataTitle="Title"
    MetadataArtist="Artist"
    MetadataArtworkUrl="http://www.myownpersonaldomain.com/image.jpg" />

    MediaElement.MetadataTitle="Title";
    MediaElement.MetadataArtist="Artist";
    MediaElement.MetadataArtworkUrl="http://www.myownpersonaldomain.com/image.jpg";

로컬 미디어 재생

로컬 미디어는 다음 소스에서 재생할 수 있습니다.

• URI 체계를 사용하여 플랫폼 애플리케이션에 embed:// 포함된 리소스입니다.
• URI 체계를 사용하여 filesystem:// 앱의 로컬 파일 시스템에 있는 파일입니다.

앱 패키지에 포함된 미디어 재생

A MediaElement 는 URI 체계를 사용하여 embed:// 앱 패키지에 포함된 미디어 파일을 재생할 수 있습니다. 미디어 파일은 플랫폼 프로젝트에 배치하여 앱 패키지에 포함됩니다.

로컬 리소스에서 재생을 위해 미디어 파일을 사용하도록 설정하려면 .NET MAUI 프로젝트의 Resources/Raw 폴더에 파일을 추가합니다. 루트에 파일이 추가되면 URI가 됩니다 embed://MyFile.mp4.

하위 폴더에 파일을 배치할 수도 있습니다. 이 MyFile.mp4 경우 사용할 URI는 다음과 입니다 Resources/Raw/MyVideosMediaElement.embed://MyVideos/MyFile.mp4

XAML에서 이 구문을 사용하는 방법의 예는 아래에서 확인할 수 있습니다.

<toolkit:MediaElement Source="embed://MyFile.mp4"
              ShouldShowPlaybackControls="True" />

MediaSource 형식 이해

A는 MediaElement 해당 Source 속성을 원격 또는 로컬 미디어 파일로 설정하여 미디어를 재생할 수 있습니다. 이 속성은 Source 형식 MediaSource이며, 이 클래스는 세 가지 정적 메서드를 정의합니다.

• FromFile는 인수에서 인스턴스를 반환 FileMediaSource 합니다 string .
• FromUri는 인수에서 인스턴스를 반환 UriMediaSource 합니다 Uri .
• FromResource는 인수에서 인스턴스를 반환 ResourceMediaSource 합니다 string .

또한 클래스에는 MediaSource 인스턴스와 MediaSource 인수를 string 반환 Uri 하는 암시적 연산자도 있습니다.

클래스에는 MediaSource 다음과 같은 파생 클래스도 있습니다.

• FileMediaSource에서 로컬 미디어 파일을 지정하는 데 사용되는 입니다 string. 이 클래스에는 로 Path 설정할 수 있는 속성이 있습니다 string. 또한 이 클래스에는 개체로 변환하는 암시적 연산자와 개체를 .로 변환 stringFileMediaSource 하는 암시적 연산자가 있습니다FileMediaSource.string
• UriMediaSourceURI에서 원격 미디어 파일을 지정하는 데 사용되는 입니다. 이 클래스에는 로 Uri 설정할 수 있는 속성이 있습니다 Uri.
• ResourceMediaSource- 앱의 리소스 파일을 통해 제공되는 포함된 파일을 지정하는 데 사용됩니다. 이 클래스에는 로 Path 설정할 수 있는 속성이 있습니다 string.

비디오 가로 세로 비율 변경

이 속성은 Aspect 비디오 미디어의 크기를 표시 영역에 맞게 조정하는 방법을 결정합니다. 기본적으로 이 속성은 열거형 멤버로 AspectFit 설정되지만 열거형 멤버로 Aspect 설정할 수 있습니다.

• AspectFit 는 가로 세로 비율을 유지하면서 비디오의 표시 영역에 맞게 필요한 경우 레터박스로 표시됨을 나타냅니다.
• AspectFill 는 가로 세로 비율을 유지하면서 표시 영역을 채우도록 비디오가 잘리도록 함을 나타냅니다.
• Fill 는 표시 영역을 채우기 위해 비디오가 늘어나게 됨을 나타냅니다.

상태 확인 MediaElement

클래스는 MediaElement 형식CurrentState의 읽기 MediaElementState전용 바인딩 가능 속성을 정의합니다. 이 속성은 미디어 재생 또는 일시 중지 여부 또는 미디어를 재생할 준비가 되지 않은 경우와 같은 컨트롤의 현재 상태를 나타냅니다.

MediaElementState 열거형은 다음 멤버를 정의합니다.

• None 는 미디어가 MediaElement 없음을 나타냅니다.
• Opening 는 지정된 원본의 MediaElement 유효성을 검사하고 로드하려고 했음을 나타냅니다.
• Buffering 는 MediaElement 재생을 위해 미디어를 로드하고 있음을 나타냅니다. 해당 속성은 Position 이 상태 동안 진행되지 않습니다. MediaElement 비디오를 재생하는 경우 마지막으로 표시된 프레임을 계속 표시합니다.
• Playing 는 미디어 원본을 MediaElement 재생 중임을 나타냅니다.
• Paused 는 속성이 MediaElement 진행되지 않음을 Position 나타냅니다. MediaElement 비디오를 재생하는 경우 현재 프레임을 계속 표시합니다.
• Stopped 는 미디어가 MediaElement 포함되어 있지만 재생되거나 일시 중지되지 않음을 나타냅니다. 해당 Position 속성은 0으로 다시 설정되며 진행되지 않습니다.
• Failed 는 MediaElement 미디어를 로드하거나 재생하지 못했음을 나타냅니다. 이 문제는 새 미디어 항목을 로드하는 동안, 미디어 항목을 재생하려고 시도하거나 오류로 인해 미디어 재생이 중단되는 경우에 발생할 수 있습니다. 이벤트를 MediaFailed 사용하여 추가 세부 정보를 검색합니다.

일반적으로 전송 컨트롤을 사용할 CurrentState 때 속성을 검사 MediaElement 할 필요가 없습니다. 그러나 이 속성은 사용자 고유의 전송 컨트롤을 구현할 때 중요합니다.

사용자 지정 전송 컨트롤 구현

미디어 플레이어의 전송 컨트롤에는 재생, 일시 중지 및 중지 함수를 수행하는 단추가 포함됩니다. 이러한 단추는 일반적으로 텍스트보다는 친숙한 아이콘으로 식별되며, 재생과 일시 중지 기능은 일반적으로 하나의 단추에 결합됩니다.

기본적으로 MediaElement 재생 컨트롤은 사용하지 않도록 설정됩니다. 이를 통해 프로그래밍 방식으로 또는 고유한 전송 컨트롤을 제공하여 제어 MediaElement 할 수 있습니다. 이를 MediaElement 지원하기 위해 , Play및 Pause 메서드를 포함합니다Stop.

다음 XAML 예제에서는 사용자 지정 전송 컨트롤이 포함된 MediaElement 페이지를 보여 줍니다.

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"
             x:Class="MediaElementDemos.CustomTransportPage"
             Title="Custom transport">
    <Grid>
        ...
        <toolkit:MediaElement x:Name="mediaElement"
                      ShouldAutoPlay="False"
                      ... />
        <HorizontalStackLayout BindingContext="{x:Reference mediaElement}"
                     ...>
            <Button Text="Play"
                    HorizontalOptions="Center"
                    Clicked="OnPlayPauseButtonClicked">
                <Button.Triggers>
                    <DataTrigger TargetType="Button"
                                 Binding="{Binding CurrentState}"
                                 Value="{x:Static toolkit:MediaElementState.Playing}">
                        <Setter Property="Text"
                                Value="Pause" />
                    </DataTrigger>
                    <DataTrigger TargetType="Button"
                                 Binding="{Binding CurrentState}"
                                 Value="{x:Static toolkit:MediaElementState.Buffering}">
                        <Setter Property="IsEnabled"
                                Value="False" />
                    </DataTrigger>
                </Button.Triggers>
            </Button>
            <Button Text="Stop"
                    HorizontalOptions="Center"
                    Clicked="OnStopButtonClicked">
                <Button.Triggers>
                    <DataTrigger TargetType="Button"
                                 Binding="{Binding CurrentState}"
                                 Value="{x:Static toolkit:MediaElementState.Stopped}">
                        <Setter Property="IsEnabled"
                                Value="False" />
                    </DataTrigger>
                </Button.Triggers>
            </Button>
        </HorizontalStackLayout>
    </Grid>
</ContentPage>

이 예제에서는 사용자 지정 전송 컨트롤이 개체로 Button 정의됩니다. 그러나 첫 번째 Button 개체는 재생 및 일시 중지Button고 두 번째 개체는 중지Button두 개뿐입니다. DataTrigger개체는 단추를 사용하거나 사용하지 않도록 설정하고 재생과 일시 중지 간에 첫 번째 단추를 전환하는 데 사용됩니다. 데이터 트리거에 대한 자세한 내용은 .NET MAUI 트리거를 참조 하세요.

코드 숨김 파일에는 이벤트에 대한 Clicked 처리기가 있습니다.

void OnPlayPauseButtonClicked(object sender, EventArgs args)
{
    if (mediaElement.CurrentState == MediaElementState.Stopped ||
        mediaElement.CurrentState == MediaElementState.Paused)
    {
        mediaElement.Play();
    }
    else if (mediaElement.CurrentState == MediaElementState.Playing)
    {
        mediaElement.Pause();
    }
}

void OnStopButtonClicked(object sender, EventArgs args)
{
    mediaElement.Stop();
}

재생 단추가 활성화되면 재생을 시작할 수 있습니다. 일시 중지 단추를 누르면 재생이 일시 중지됩니다. 중지 단추를 누르면 재생이 중지되고 미디어 파일의 위치가 시작 부분으로 돌아갑니다.

사용자 지정 볼륨 컨트롤 구현

각 플랫폼에서 구현되는 미디어 재생 컨트롤에는 볼륨 막대가 포함됩니다. 이 막대는 슬라이더와 유사하며 미디어 볼륨을 보여 줍니다. 또한 볼륨 막대를 조작하여 볼륨을 늘리거나 줄일 수 있습니다.

다음 예제와 같이 사용자 지정 볼륨 막대를 Slider사용하여 구현할 수 있습니다.

<StackLayout>
    <toolkit:MediaElement ShouldAutoPlay="False"
                          Source="{StaticResource AdvancedAsync}" />
    <Slider Maximum="1.0"
            Minimum="0.0"
            Value="{Binding Volume}"
            Rotation="270"
            WidthRequest="100" />
</StackLayout>

이 예제에서 Slider 데이터는 해당 Value 속성을 .의 Volume속성에 MediaElement 바인딩합니다. 이 속성은 바인딩을 VolumeTwoWay 사용하므로 가능합니다. 따라서 속성을 변경 Value 하면 속성이 Volume 변경됩니다.

참조를 Slider 사용하는 방법에 대한 자세한 내용은 .NET MAUI 슬라이더

리소스 정리 MediaElement

메모리 누수 방지를 위해 리소스를 해제해야 합니다 MediaElement. 처리기의 연결을 끊어 이 작업을 수행할 수 있습니다. 이 작업을 수행해야 하는 위치는 앱에서 사용하는 MediaElement 위치와 방법에 따라 달라지지만, 일반적으로 단일 페이지에 있고 백그라운드에서 미디어를 재생하지 않는 경우 MediaElement 사용자가 페이지에서 벗어날 때 리소스를 해제하려고 합니다.

아래에서 이 작업을 수행하는 방법을 보여주는 샘플 코드 조각을 찾을 수 있습니다. 먼저 페이지에서 이벤트를 연결 Unloaded 해야 합니다.

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"
             x:Class="MediaElementDemos.FreeResourcesPage"
             Title="Free Resources"
             Unloaded="ContentPage_Unloaded">
    
    <toolkit:MediaElement x:Name="mediaElement"
                          ShouldAutoPlay="False"
                          ... />
</ContentPage>

그런 다음 코드 숨김에서 메서드를 호출하여 처리기의 연결을 끊습니다.

public partial class FreeResourcesPage : ContentPage
{
    void ContentPage_Unloaded(object? sender, EventArgs e)
    {
        // Stop and cleanup MediaElement when we navigate away
        mediaElement.Handler?.DisconnectHandler();
    }
}

처리기에 대한 자세한 내용은 처리기의 .NET MAUI 설명서를 참조하세요.

속성

Events

메서드

예제

.NET MAUI 커뮤니티 도구 키트 샘플 애플리케이션에서 작동 중인 이 컨트롤의 예제를 찾을 수 있습니다.

API

.NET MAUI 커뮤니티 도구 키트 GitHub 리포지토리에서 오버에 대한 MediaElement 소스 코드를 찾을 수 있습니다.

관련 링크

• .NET MAUI 트리거
• .NET MAUI 슬라이더
• Android ExoPlayer: 지원되는 미디어 형식
• iOS: 지원되는 미디어 형식
• Windows: 지원되는 코덱
• Android ExoPlayer 바인딩