as

Settings
Sign out
Notifications
Alexa
Amazonアプリストア
AWS
ドキュメント
Support
Contact Us
My Cases
開発
設計と開発
公開
リファレンス
サポート

ヘッドレスJavaScript再生の実装

ヘッドレスJavaScript再生の実装

このガイドでは、アプリにヘッドレス再生を実装する方法について説明します。ヘッドレス再生では、UIとは別のJavaScriptスレッドでメディア再生が実行され、複雑なUIを持つアプリの最初のビデオフレームまでの時間(TTFVF)が最大30%短縮されます。

ヘッドレス統合について

リソース競合の問題

メディア再生とUIレンダリングを同じJavaScriptスレッドで実行すると、互いに動作をブロックする状況が発生することがあります。このようなシナリオは主に、メディア再生によってUIの応答性が妨げられる場合と、UI操作によってスムーズなメディア再生が妨げられる場合の2つに分けられます。

MPEG DASHやHLSなどのストリーミング標準に対応する一般的なメディアプレーヤーの実装では、CPUとネットワークから大量のシステムリソースが消費される可能性があります。特に、再生とライブストリーミングのプロセスでは、CPU負荷の高いマニフェスト解析が必要になります。プレーヤーがUIと同じスレッドで動作していると、両方のコンポーネントがリソースを奪い合い、再生開始の遅延、ビデオ再生の途切れ、UI要素の応答停止、全体的なユーザーエクスペリエンスの低下が発生します。

ヘッドレス実装では、UIから切り離されたJSスレッドでプレーヤーを実行し、プレーヤー用のサービスコンポーネントを作成することでこれらの問題を解決します。UIコントロールは、サービスコンポーネントを操作してメディアの再生を制御できます。このシナリオでは、対話型コンポーネント内のプレーヤーUIが「クライアント」で、サービスコンポーネントを実行しているプレーヤーが「サーバー」となります。

ヘッドレス統合の利点には、再生の開始にかかる時間の短縮、UIの応答性の向上、全体的な再生パフォーマンスの向上などがあります。

アプリにヘッドレス再生を実装するには、次の3つのタスクを実行する必要があります。

  1. プレーヤーサーバーをアプリ内のサービスコンポーネントとして作成します。
  2. プレーヤーのコードを変更して、プレーヤーを直接制御するのではなくサービスを操作するようにします。
  3. アプリからサービスを開始します。

次の画像は、手順の概要と、アプリでヘッドレス再生がどのように動作するか表す図を示しています。

詳細な実装手順については、後述のヘッドレスサービスの実装を参照してください。

ヘッドレスサービスの実装

ヘッドレスサービスを実装するには、次の手順を実行します。

  1. アプリのマニフェストにコンポーネントと機能を追加します。
  2. service.jsファイルを作成します。
  3. ヘッドレスサービスファイルを作成します。
  4. プレーヤーのコードを更新します。
    1. クライアントを初期化します。
    2. ビデオの読み込みを処理します。
    3. 再生コントロールを処理します。
  5. 追加の依存関係をインストールします。

以下のセクションでは、これらの各手順について詳しく説明します。

アプリマニフェストへのコンポーネントの追加

Vegaアプリパッケージでは、パッケージのルートにmanifest.tomlという構成ファイルが含まれている必要があります。このファイルは、パッケージに関する重要な情報を記述します。

アプリにヘッドレス再生を実装するには、アプリのマニフェストでcomponentsprocesseswantsoffersの各セクションを更新する必要があります。以下の例は、セクションごとの固有の更新方法を示しています。<アプリパッケージ名>は、実際のアプリのパッケージ名に置き換えてください。

クリップボードにコピーしました。

[[components.interactive]]
id = "<アプリパッケージ名>.main"
runtime-module = "/com.amazon.kepler.keplerscript.runtime.loader_2@IKeplerScript_2_0" 
launch-type = "singleton"
categories = ["com.amazon.category.main"]

[[components.service]]
id = "<アプリパッケージ名>.service"
runtime-module = "/com.amazon.kepler.keplerscript.runtime.loader_2@IKeplerScript_2_0"
launch-type = "singleton"
.
.
.

[processes]
# プレーヤーUIとヘッドレスJSプレーヤーコンポーネントを同じプロセスグループに指定します。
[[processes.group]]
component-ids = ["<アプリパッケージ名>.main", "<アプリパッケージ名>.service"]

.
.
.

[wants]

[[wants.service]]
id = "<アプリパッケージ名>.service"

.
.
.

[offers]

[[offers.service]]
id = "<アプリパッケージ名>.service"

マニフェストの詳細については、Vegaアプリのマニフェストを参照してください。

service.jsファイルの作成

プロジェクトのルートにservice.jsファイルを作成します。service.jsファイルを使用することで、ヘッドレスJSサービスのエントリポイント(onStartServiceonStopService)を登録できます。<アプリパッケージ名>は上記のmanifest.tomlファイルで指定したアプリのパッケージ名に置き換えて、エントリポイントと終了ポイントを登録してください。

クリップボードにコピーしました。

import {HeadlessEntryPointRegistry} from '@amazon-devices/headless-task-manager';

import {onStartService, onStopService} from './src/PlayerService';

HeadlessEntryPointRegistry.registerHeadlessEntryPoint(
  '<アプリパッケージ名>.service::onStartService',
  () => onStartService,
);
HeadlessEntryPointRegistry.registerHeadlessEntryPoint(
  '<アプリパッケージ名>.service::onStopService',
  () => onStopService,
);

ヘッドレスサービスファイルの作成

./src/PlayerService.tsというヘルパーファイルを作成して、プレーヤーの初期化とコントロールを処理します。

プレーヤーコードの更新

クライアントの初期化

App.tsxファイルに以下のコードを追加して、クライアントを初期化します。

ビデオの読み込みの処理

次に、App.tsxファイルに以下のコードを追加して、ビデオの読み込みを処理します。

再生コントロールの処理

次に、App.tsxファイルに以下のコードを追加して、再生コントロールを処理します。

Vegaメディアコントロールの統合

Vegaメディアコントロール(VMC)は、Keplerを使用するメディアアプリ開発者が、メディアコントロール用のさまざまな入力モダリティを効率的に統合できるようにする機能を提供します。メディアアプリは通常、再生・一時停止・停止などのアプリ内ユーザーインターフェイスコントロールを備えていますが、ユーザーはリモコンや、Alexaのようなサービスによる音声コマンドなど、追加の操作方法を求めることがよくあります。Vegaメディアコントロールの機能はそれらの多様な入力方法の統合を処理するため、開発者は、スムーズなメディア再生というコアビジネスロジックの開発に専念できます。

ヘッドレスJS再生APIを使用してコンテンツを再生するアプリでは、無料でKMCを統合して、一時停止・再生・シークなどの基本的な再生制御を有効にすることができます。ヘッドレスJS再生APIは、内部でKMCサーバーを作成し、サーバーの状態を公開して、再生・一時停止・シークという基本的なコマンドを処理します。

ヘッドレスJS再生では、基本的な再生に関するデータについてのみKMCサーバーの状態を更新する必要があります。アプリでKMC自体を操作する場合は、ヘッドレスJS再生の統合を使用する必要はありません。コマンドを処理するには、KMCを直接統合する必要があります。この統合は、プレーヤーに対話型コンポーネントが組み込まれているユースケースにのみ適用されます。この場合、アプリでplayer.setMediaControlFocus(componentInstance)を呼び出したり、機能のオーバーライドを実装したりしないでください。

KMCにオプトインするには

  1. KMCを有効にします。Vegaメディアコントロールの使用開始の説明に従って、manifest.tomlファイルに必要なマニフェストエントリを追加します。
  2. package.jsonファイルを更新して、@amazon-devices/kepler-media-controlsへの依存関係を指定します。
  3. 対話型コンポーネントのコンポーネントインスタンスを取得します。

    クリップボードにコピーしました。

     import { useComponentInstance , IComponentInstance } from '@amazon-devices/react-native-kepler';
    
     const componentInstance: IComponentInstance = useComponentInstance();
    
  4. IPlayerClient.load APIを呼び出す前に、プレーヤーインスタンスにメディアコントロールフォーカスを設定します。

    クリップボードにコピーしました。

     playerClient.current.setMediaControlFocus(componentInstance);
    

これにより、playerClientインスタンスでKMCが有効になり、リモコンやAlexa音声制御による一時停止・再生・シークの基本機能がサポートされます。

特定の制御コマンドのオーバーライド

場合によっては、ヘッドレスJS再生APIがデフォルトで実行する特定の制御コマンドの処理を、アプリでオーバーライドすることが必要になります。たとえば、ライブコンテンツの再生中にシークを無効にすることができます。ヘッドレスJS再生APIには、このような動作を実現する方法も用意されています。

  1. @amazon-devices/kepler-player-clientによって提供されるPlayerClientMediaControlHandlerを継承し、アプリでオーバーライドする必要のある関数をオーバーライドします。

    クリップボードにコピーしました。

     import { PlayerClientMediaControlHandler } from "@amazon-devices/kepler-player-client";
     import { IMediaSessionId } from '@amazon-devices/kepler-media-controls';
    
     class AppOverrideMediaControlHandler extends PlayerClientMediaControlHandler {
         async handlePlay(mediaSessionId?: IMediaSessionId) {
             if(shouldOverride) {
                 // アプリの要件に従ってカスタム処理を実行します。
             } else {
                 // デフォルトハンドラーを呼び出します。
                 super.handlePlay(mediaSessionId);
             }
         }
     };
    
  2. setMediaControlFocusメソッドに、アプリのメディアコントロールハンドラーを第2パラメーターとして渡します。

    クリップボードにコピーしました。

     playerClient.current.setMediaControlFocus(componentInstance, new AppOverrideMediaControlHandler());
    

追加の依存関係のインストール

ヘッドレスサービスを使用するには、次のパッケージをインストールする必要があります。

  • @amazon-devices/kepler-player-server
  • @amazon-devices/kepler-player-client
  • @amazon-devices/react-native-w3cmedia

これらの依存関係をアプリのpackage.jsonに追加します。例は次のとおりです。

クリップボードにコピーしました。

"dependencies": {
    "@amazon-devices/headless-task-manager": "^1.0.0",
    "@amazon-devices/kepler-player-server": "^2.0.4",
    "@amazon-devices/kepler-player-client": "^2.0.4",
    "@amazon-devices/keplerscript-turbomodule-api": "^1.2.1",
    "@amazon-devices/react-native-kepler": "~2.0.0",
    "@amazon-devices/react-native-w3cmedia": "^2.1.66",
    "base-64": "*",
    "react": "18.2.0",
    "react-native": "0.72.0",
    "xmldom": "*"
  },

ベストプラクティス

バックグラウンドモード

アプリがバックグラウンドに移行したときは、UIからIPlayerClient::unloadSyncを呼び出して、メディアプレーヤーの読み込みを解除することをお勧めします。同様に、ヘッドレスJSサービスでは、onStopServiceコールバックでメディアプレーヤーの読み込みを解除し、必要なクリーンアップを実行する必要があります。


Last updated: 2025年10月1日