VegaメディアコントロールAPIリファレンス
このAPIに関するリファレンスドキュメントについては、amzn/kepler-media-controlsを参照してください。Vegaメディアコントロールの前提条件
次に挙げる前提条件は、メディアプロバイダーアプリの開発にのみ適用され、クライアントメソッドを使用する場合は適用されません。クライアントメソッドを使用する場合は、事前に、アプリマニフェストを更新して、VegaメディアコントロールAPIを使用する意図を明示的に宣言する必要があります。マニフェストエントリを変更するときは、以下の例に示すように、com.amazondeveloper.media.sampleをアプリの実際のパッケージIDに必ず置き換えてください。この手順を踏むことにより、アプリがVegaメディアコントロールAPIと対話するように正しく構成されます。
アプリで受け取ることができるコマンドと属性は、マニフェスト構成によって制御されます。次の3つのカテゴリーがあります。
- コアコマンドおよび属性 - マニフェストの構成を必要とせずに常にアプリに配信されます。これには、
Play、Pause、Stop、TogglePlayPauseなどの基本的な再生コマンドと、CurrentState、AvailableActions、MediaSessionStatesなどの属性が含まれます。完全な一覧については、コアコマンドとコア属性を参照してください。 - オプションコマンド（
command_options）-command_options配列に指定することで個別に有効にするコマンドです。この配列にコマンドを含めていない場合、そのコマンドのリクエストはアプリに送信されません。完全な一覧については、オプションコマンドを参照してください。 - フィーチャーゲートで制御されるコマンドおよび属性（
features）- それぞれの機能により、関連するコマンドと属性のグループが有効化されます。機能が提供するコマンドと属性を受け取るには、その機能をfeatures配列に追加する必要があります。機能が構成されていない場合、ハンドラーを実装しても、それらのコマンドと属性はアプリに配信されません。たとえば、FastForwardイベントとRewindイベントを受け取るには、features配列に"VariableSpeed"を含める必要があります。各機能の詳細と、その機能で有効になるコマンドおよび属性については、機能を参照してください。
Vegaメディアコントロールのインストールと設定
APIを使用するには、package.jsonに次の依存関係を追加します。
Vegaメディアコントロールの一般的なユースケース
メディアコンテンツプロバイダーアプリの場合
プロバイダーアプリでメディアセッションの状態を管理するには、MediaPlayerStateクラスを実装します。このクラスは、メディアセッションに必要なすべてのプロパティをカプセル化します。これには、再生状態、トラック情報、再生時間、現在位置、再生速度、使用可能なメディア操作などが含まれます。
MediaPlayerStateクラスには、メディアセッションの状態が変化したときにこれらのプロパティを更新するメソッドが用意されています。これらのメソッドに加えてgetServerState()などのメソッドを含めると、現在のプロパティ値に基づいて有効なMediaSessionStateオブジェクトを構築して返すことができます。メディアセッションが変更されたときに必ずMediaPlayerStateインスタンスを更新すると、MediaSessionStateオブジェクトにメディアプレーヤーの最新状態を正確に反映でき、これにより状態管理が一元化されて同期が簡単になります。
複数のビデオの同時再生をサポートするメディアプロバイダーの場合、セッションごとに個別のMediaPlayerStateオブジェクトを管理し、インスタンスごとにmSessionIdが正しく更新されていることを確認してください。このアプローチにより、アプリ内の複数のメディアセッションを効率的に管理できます。
IMediaControlHandlerAsyncインターフェイスを実装するMediaControlHandlerAsyncクラスを作成します。このクラスには、メディア再生コントロールを管理するためのhandlePlayやhandlePauseなどのコールバック関数が用意されています。これらの関数は、TypeScriptにおけるPromiseベースのメソッドを使用してノンブロッキング実行を保証します。また、このクラスには、以前に作成したMediaPlayerStateクラスを使用してメディアセッションの状態を非同期的に返すコールバックも実装されています。
記載されているコード例では、当メソッドのサブセットのみを実装しています。完全な実装には、IMediaControlHandlerAsyncインターフェイスのすべてのメソッドが含まれます。ほとんどのコールバック関数は、要求されたアクションを実行するセッション識別子を示すIMediaSessionIdインターフェイスオブジェクトのインスタンスを受け取ります。このことは、メディアプロバイダーアプリが複数のセッションをサポートしている場合に特に重要です。sessionIdの値が空白あるいは未設定の場合、デフォルトで、プロバイダーアプリはデフォルトのセッションでアクションを実行します。このアプローチにより、アプリ内の単一または複数のメディアセッションにおいて、メディアコントロールリクエストが適切に処理されるようになります。
MediaControlHandlerAsyncクラスはhandleGetMetadataInfoメソッドを実装する必要があります。後者のメソッドはIMediaControlHandlerAsyncインターフェイス内に定義されているメソッドの1つです。このメソッドは、当該のセッションで現在再生されているメディアのメタデータを返す処理を行います。
メディアのメタデータ情報は、IMediaMetadataデータオブジェクトを使用して表されます。このデータオブジェクトには、メディアID、作曲家、アーティスト、再生ソースなどのさまざまなプロパティが含まれています。記載されているコード例では、handleGetMetadataInfoの実装によって、IMediaMetadataオブジェクトを作成して返す方法が示されています。わかりやすくするために、この例ではインラインオブジェクトを使用してメタデータを表します。ただし、本番環境では、IMediaMetadataデータオブジェクトを実装する独立したクラスを作成するアプローチをお勧めします。この独立したクラスは、メディアメタデータを処理するための専用のデータオブジェクトとして機能し、メディア属性のより包括的表現を可能にすると同時に、コードの構造を改善して保守しやすくします。
MediaControlHandlerAsyncクラスコンストラクターは、メディアコントロール機能をセットアップする上で重要な役割を果たします。このコンストラクターは、MediaControlServerComponentAsyncの単一インスタンスを作成します。これは、メディアコントロールの操作を非同期的に処理するコアコンポーネントの役割を果たします。
このコンストラクターでは、IComponentInstanceオブジェクトを登録するステップが重要になります。このオブジェクトはパラメーターとしてコンストラクターに渡された後、MediaControlServerComponentAsyncインスタンスに登録されます。登録プロセスが重要な理由は、メディアコントロールハンドラーと、メディアコントロールコールバックを受信するアプリ内の特定コンポーネントとのリンクが確立されるためです。
複数のコンポーネントを含むアプリでは、この登録が特に重要になります。適切なIComponentInstanceをMediaControlHandlerAsyncコンストラクターに渡すことで、メディアコントロールコールバックが適切なコンポーネントに確実に送信されます。ターゲットを絞ったこのアプローチは、メディアコントロールがアプリの意図した部分のみに作用するようにし、混乱を防ぎます。
useComponentInstanceメソッドを使ってIComponentInstanceのインスタンスを取得し、次にReact NativeのuseEffectフックの処理の中でMediaControlHandlerAsyncのインスタンスを作成できます。このアプローチを実装する方法は次のとおりです。
useComponentInstanceメソッドを使用してIComponentInstanceのインスタンスを取得します。- 次に、Reactコンポーネントで
useEffectフックを使用してMediaControlHandlerAsyncインスタンスを作成し、このインスタンスをコンストラクターのパラメーターとして渡します。このように設定することで、コンポーネントがマウントされるとすぐに、MediaControlHandlerAsyncオブジェクトが適切なIComponentInstanceオブジェクトで初期化されます。
IComponentInstanceオブジェクトの可用性に密接に結び付けられます。
メディアコントロールのクライアントアプリの場合
VegaメディアコントロールAPIのクライアントメソッドは、メディアのエコシステムにおいて重要な役割を果たします。主な役割は、playやpause、その他のサポートされているアクションのさまざまなコマンドを、メディアプロバイダーアプリに簡単に送信できるようにすることです。クライアントメソッドを使用すると、単一のインターフェイスで一元的に複数のメディアソースを制御できるメディアハブソリューションなど、多様なアプリを柔軟に作成できます。
また、テスト目的で使用して、メディアプロバイダーアプリがhandlePlayやhandlePauseなどのコマンドおよび関連する引数を正しく受信して処理するかどうかを検証することもできます｡このテスト機能を使用することで、メディアプロバイダーアプリがユーザー入力に適切に応答するようにでき、迅速に応答するシームレスなメディア再生体験を維持できるようになります。
VegaメディアコントロールクライアントAPIを使用するには、MediaAppLocatorというヘルパークラスをシングルトンクラスとして作成します。このクラスを使用して、MediaControlComponentAsync.makeMediaControlEndpointLocator()を呼び出してメディアアプリロケーターのインスタンスを取得します。これにより、IMediaControlEndpointLocatorAsyncインターフェイスを実装するオブジェクトが返されます。
VegaメディアコントロールAPIを使用していて、かつデバイスにインストールされているメディアプロバイダーアプリを取得するには、このインスタンスを使用します。エンドポイントロケーターインターフェイスは、メディアコントロールプロバイダーアプリのランキングリストを取得します。ランキングは、アプリのフォーカスによって変わります。通常、ランキングリストの最初のアプリは、現在表示されていてアクティブなフォーカスがあるアプリです。エンドポイントはTypeScriptのPromiseベースのメソッドを使用して非同期でフェッチされるため、取得プロセス中にメインスレッドがブロックされることはなく、アプリの応答性が維持されます。
VegaメディアコントロールAPIのクライアントメソッドには、APIの機能と応答性を強化する追加機能があります。クライアントアプリはaddChangeListenerメソッドを呼び出すことで、デバイスで利用可能なメディアエンドポイントの変更を監視するリスナーを登録できます。このリスニング機能は特に、メディアアプリのリストをほぼリアルタイムで最新状態に維持するために役立ちます。
デバイスのメディアエンドポイントの状態が変わるのは、新しいメディアアプリをインストールしたり既存のメディアアプリをアンインストールしたりした場合です。このリスナーを実装すると、手動でポーリングや更新を行わなくても、そのような変更をクライアントアプリで自動的に検出できます。これにより、クライアントアプリには、利用可能なメディアアプリに関する最新情報が常に保持されます。
リスナーは、変更が発生したときに適切なアクションをトリガーするように設定できます。変更としては、ユーザーインターフェイスの更新、利用可能なメディアコントロールのリストの更新、利用可能なメディアエンドポイントの新しい組み合わせに応じたアプリ動作の調整などがあります。このリアルタイムの応答性により、クライアントアプリとデバイスのメディアエコシステムの同期が維持され、ユーザーエクスペリエンスが大幅に向上します。
IMediaControlClientAsyncオブジェクトのランクキングリストとして返します。このランキングはアプリのフォーカスに基づいており、リストの最初のエンドポイントは現在アクティブフォーカスがあるアプリを表しています。各IMediaControlClientAsyncオブジェクトを使用することで、特定のメディアアプリを操作できます。これらのオブジェクトにより、クライアントアプリはplayやpauseなどの制御コマンドを特定のメディアアプリに直接送信できます。
Vegaメディアコントロールのクライアントメソッドは、複数のメディアセッションをサポートします。この機能は、複数のビデオ再生モードやピクチャインピクチャモードなどの高度な機能に対応するように設計されています。この機能を使用するには、すべてのクライアントメソッドでオプションのセッションIDパラメータを受け入れます。このメソッドを使用する場合にセッションIDを省略すると、プロバイダーアプリは、アクションをデフォルトセッションで実行します｡これに対し、セッションIDを指定した場合は、その特定のセッションに対してアクションが実行されます。この柔軟性により、1つのアプリ内で複数の同時メディアセッションを正確に制御できます。
IGetMediaControlEndpointsResponseListenerインターフェイスを使用します。この機能を使用するには、IMediaControlEndpointLocatorListenerインターフェイスを実装するクラスまたは構造体を作成する必要があります。このリスナーは、新しいプロバイダーアプリがインストールされたり既存のプロバイダーアプリがアンインストールされたりするなどの変更がメディアプロバイダーアプリ一覧内で発生するたびに、自動的に呼び出されます。コールバックは、トリガーされたときに、発生した具体的な変更に関する情報を提供するだけではなく、更新されたプロバイダーアプリ一覧全体を送信します。このアプローチにより、クライアントアプリは常にメディアプロバイダーの完全な最新状況を把握できます。完全な最新リストを受け取ることで、アプリの状態を現在のデバイス構成と同期させることができるため、個々の変更を追跡する必要がなくなり、メディアコントロールのエコシステムにおける不整合のリスクが減少します。
addListenerメソッドによって実現されています。この状態オブジェクトは、メディアプロバイダーアプリからupdateMediaSessionStatesメソッドを通じてVegaメディアコントロールシステムに伝達されます。
この機能は、メディアの再生ステータスやその他の関連するステータス情報をリアルタイムで把握し続けるために不可欠です。この機能を実装するには、addListenerメソッドを使用して、指定したメディアアプリの状態が変更されるたびに呼び出されるコールバック関数を登録します。通知される更新には、再生ステータスやトラック情報、その他の関連するメディアセッションデータの変更が含まれます。
addListenerメソッドはISubscriptionのインスタンスを返します。このオブジェクトには、不要になったサブスクリプションをキャンセルするメソッドが用意されています。ISubscriptionオブジェクトに対してキャンセル用メソッドを呼び出すことで、不要なコールバックの実行を防いで、リソースを効率的に管理することができます。
このリスニング機能により、クライアントアプリは、メディアアプリ状態の変化に動的に反応できるようになるので、絶えずポーリングしなくてもよくなります。これにより、最新のメディア再生ステータスをリアルタイムで正確に反映する、応答性の高いユーザーインターフェイスを作成できます。addListenerメソッドをディスプレイの更新、コントロールの調整、他のアプリコンポーネントとの同期で使用すると、アプリをターゲットエンドポイントのメディア再生状態と完全に同期させることができます。
IMediaControlListenerインターフェイスで使用できるaddListenerメソッドによってイベント駆動型の更新を行えるほかにも、getSessionStateメソッドでは最新のメディアセッションオブジェクトをいつでも明示的にリクエストできます。この機能は非同期で動作し、システムの応答性を維持します。特定のメディアセッションIDを指定してこのメソッドを呼び出すと、そのセッションのセッション状態情報が返されます。それ以外の場合は、利用可能なすべてのセッションの情報が返されます。これにより、アプリのニーズに基づいてリクエストを微調整できます。この場合、すべてのアクティブなメディアセッションの大まかな概要が必要か、または特定のメディアセッションの詳細情報が必要かを問いません。
この明示的なリクエスト機能とイベント駆動型の更新を組み合わせることで、Vegaメディアコントロールシステムでは、単純なメディアプレーヤーから複雑なメディア管理アプリに至るさまざまなシナリオでメディアコントロールを管理することができます。
