2016/11/07

Android: ExoPlayer - Demo application

翻訳ページ:
https://google.github.io/ExoPlayer/demo-application.html

Demo application

The ExoPlayer demo app serves two primary purposes:

  • To provide a relatively simple yet fully featured example of ExoPlayer usage. The demo app can be used as a convenient starting point from which to develop your own application.
  • To make it easy to try ExoPlayer. The demo app can be used to test playback of your own content in addition to the included samples.

This page describes how to get, compile and run the demo app. It also describes how to use it to play your own media.

ExoPlayerのデモアプリは次の2つの大きな理由のために用意してあります:

  • シンプルでありながら全てのExoPlayer機能の使い方を例示していること. デモアプリがアプリ開発を始める際の開始点としてとして便利であること.
  • ExoPlayerをお手軽に試すことができること. デモアプリにオリジナルコンテンツを追加して再生のテストにも使えること.

このページではどうやってデモアプリを取得し, コンパイルし, 実行するのかを説明します.
また, あなたが用意したメディアをどうやって再生するのかについても説明します.

Getting the code

The source code for the demo app can be found in the demo folder of our GitHub project. If you haven’t already done so, clone the project into a local directory:

git clone https://github.com/google/ExoPlayer.git

Next, open the project in Android Studio. You should see the following in the Android Project view (the relevant folders of the demo app have been expanded):

デモアプリのソースコードはGitHubプロジェクトから取得できます. まだ取得していないのであればローカルディレクトリにcloneしてください.

git clone https://github.com/google/ExoPlayer.git

次に, AndroidStudioでAndroid Projectビューを開くと次の表示を確認できます.

Figure 1. The project in Android Studio

Compiling and running

To compile and run the demo app, select and run the demo configuration in Android Studio. The demo app will install and run on a connected Android device. We recommend using a physical device if possible. If you wish to use an emulator instead, please read FAQ - Does ExoPlayer support emulators? and ensure that your Virtual Device uses a system image with an API level of at least 23.

AndroidStudioのConfigurationからdemoを選択し, デモアプリをコンパイル, 実行してください. 接続されているデバイスにデモアプリがインストールされて実行されます. 可能であればエミュレータではなく物理的なデバイスの使用を推奨します.

もし代わりにエミュレータを使用したいのであればFAQ - Does ExoPlayer support emulators?を読んでください. そうすればAPI lv23以降の仮想デバイスで使うことができます.

Figure 2. SampleChooserActivity and PlayerActivity

The demo app presents of a list of samples (SampleChooserActivity). Selecting a sample will open a second activity (PlayerActivity) for playback. The demo features playback controls and track selection functionality. It also has an EventLogger class that outputs useful debug information to the system log. This logging can be viewed (along with error level logging for other tags) with the command:

デモアプリのSampleChooserActivityにサンプルのリストがあります. リスト項目を選択すればそれを再生するためのPlayerActivityが起動します. デモは再生コントロールとトラック選択の機能を持っています. また, システムログに有用なデバッグ情報を出力するEventLoggerクラスを持っています. 次のコマンドでEventLoggerの有効にして, ほかのログはエラー情報のみ表示することができます.

adb logcat EventLogger:V *:E

Including extension decoders

ExoPlayer has a number of extensions that allow use of bundled software decoders, including VP9, Opus, FLAC and FFMPEG (audio only). The demo app can be built to include and use these extensions as follows:

  1. Build each of the extensions that you want to include. Note that this is a manual process. Refer to the README.md file in each extension for instructions.
  2. In Android Studio’s Build Variants view, change the build variant for the demo module from demoDebug to demo_extDebug, as shown in Figure 3.
  3. Compile, install and run the demo configuration as normal.

ExoPlayerはいくつかのエクステンションがありVP9, Opus, FLAC and FFMPEG (audio only)といったソフトウェアデコーダを使うことができます. デモアプリでこれらを使うための手順は次の通りです:

  1. 取り込みたいExtensionをビルドします. これは手作業での変更になります. それぞれのExtensionにあるReadmeには手順が示されています.
  2. Figure 3を参考に, AndroidStudioのビルドバリアントビューでデモモジュールのビルドバリアントをdemoDebugからdemo_extDebugに切り替えます.
  3. いつもの通りデモをコンパイル, インストール, 実行します.


Figure 3. Selecting the demo_extDebug build variant

By default an extension decoder will be used only if a suitable platform decoder does not exist. It is possible to indicate that extension decoders should be preferred, as described in the sections below.

デフォルトのデコーダ拡張は適切なプラットフォームデコーダが存在しない時だけ使われる。これはのそセクションで拡張デコーダが望ましいことを示すことができる。

Playing your own content

There are multiple ways to play your own content in the demo app.

デモアプリで手持ちのコンテンツを再生するにはいくつかの方法があります.

1. Editing assets/media.exolist.json

The samples listed in the demo app are loaded from assets/media.exolist.json. By editing this JSON file it’s possible to add and remove samples from the demo app. The schema is as follows, where [O] indicates an optional attribute.

デモアプリではasset/media.exolist.jsonから読み込まれたサンプルコンテンツがリストされています. このJSONファイルを編集することでこれらのサンプルに追加したり削除したりすることができます. JSONの形式は次の通り. [O]はオプションの属性です.

[
  {
    "name": "Name of heading",
    "samples": [
      {
        "name": "Name of sample",
        "uri": "The URI/URL of the sample",
        "extension": "[O] Sample type hint. Values: mpd, ism, m3u8",
        "prefer_extension_decoders": "[O] Boolean to prefer extension decoders",
        "drm_scheme": "[O] Drm scheme if protected. Values: widevine, playready",
        "drm_license_url": "[O] URL of the license server if protected",
        "drm_key_request_properties": "[O] Key request headers if protected"
      },
      ...etc
    ]
  },
  ...etc
]

Playlists of samples can be specified using the schema:

サンプルのプレイリストはスキーマを使って特定できる.

[
  {
    "name": "Name of heading",
    "samples": [
      {
        "name": "Name of playlist sample",
        "prefer_extension_decoders": "[O] Boolean to prefer extension decoders",
        "drm_scheme": "[O] Drm scheme if protected. Values: widevine, playready",
        "drm_license_url": "[O] URL of the license server if protected",
        "drm_key_request_properties": "[O] Key request headers if protected"
        "playlist": [
          {
            "uri": "The URI/URL of the first sample in the playlist",
            "extension": "[O] Sample type hint. Values: mpd, ism, m3u8"
          },
          {
            "uri": "The URI/URL of the first sample in the playlist",
            "extension": "[O] Sample type hint. Values: mpd, ism, m3u8"
          },
          ...etc
        ]
      },
      ...etc
    ]
  },
  ...etc
]

If required, key request headers are specified as an object containing a string attribute for each header:

もし必要なら, それぞれのヘッダに文字列を含むオブジェクトのキーリクエストヘッダを指定できます.

"drm_key_request_properties": {
  "name1": "value1",
  "name2": "value2",
  ...etc
}

2. Loading an external exolist.json file

The demo app can load external JSON files using the schema above and named according to the *.exolist.json convention. For example if you host such a file at https://yourdomain.com/samples.exolist.json, you can open it in the demo app using:

デモアプリは上記のスキーマを使った*.exolist.jsonにマッチするJSONを読み込むことができます. もしファイルをhttps://yourdomain.com/samples.exolist.jsonでホストしているならデモアプリを使って次のコマンドで開くことができます.

adb shell am start -d https://yourdomain.com/samples.exolist.json

Clicking a *.exolist.json link (e.g. in the browser or an email client) on a device with the demo app installed will also open it in the demo app. Hence hosting a *.exolist.json JSON file provides a simple way of distributing content for others to try in the demo app.

ブラウザやemailクライアントで*.exolist.jsonのリンクをクリックするとデモアプリがインストールされていれば起動することができます. デモアプリで試すには*.exolist.jsonのJSONファイルをホストするのがコンテンツを他へ配信するのに簡単な方法です.

3. Firing an intent

Intents can be used to bypass the list of samples and launch directly into playback. To play a single sample set the intent’s action to com.google.android.exoplayer.demo.action.VIEW and its data URI to that of the sample to play. Such an intent can be fired from the terminal using:

Intentはサンプルリストをバイパスするのと直接再生することに使えます. 1つのサンプルセットを再生するにはアクションcom.google.android.exoplayer.demo.action.VIEWとデータのURIが設定されたIntentを使います. そうしたIntentをターミナルから発行するには次のコマンドを使います.

adb shell am start -a com.google.android.exoplayer.demo.action.VIEW \
    -d https://yourdomain.com/sample.mp4

Supported optional extras for a single sample intent are:

  • extension [String] Sample type hint. Valid values: mpd, ism, m3u8
  • prefer_extension_decoders [Boolean] Whether extension decoders are preferred to platform ones
  • drm_scheme_uuid [String] Drm scheme UUID if protected
  • drm_license_url [String] Url of the license server if protected
  • drm_key_request_properties [String array] Key request headers packed as name1, value1, name2, value2 etc. if protected

IntentがサポートしているオプショナルなExtraは次の通り:

  • extension [String] サンプルの種類. 使える値は mpd ism m3u8
  • prefer_extension_decoders [Boolean] extensionデコーダーがプラットフォームに適しているかどうか
  • drm_scheme_uuid [String] 保護されている場合のDrm形式のUUID
  • drm_license_url [String] 保護されている場合のライセンスサーバーURL
  • drm_key_request_properties [String array] 保護されている場合, name1, value1, name2, value2の形でパッケージされたキーリクエストヘッダ

When using adb shell am start to fire an intent, an optional string extra can be set with --es (e.g. --es extension mpd). An optional boolean extra can be set with --ez (e.g. --ez prefer_extension_decoders TRUE). An optional string array extra can be set with --esa (e.g. --esa drm_key_request_properties name1,value1).

Intentの発行にadb shell am startを使うなら, Extraオプションの文字列は--es (e.g. --es extension mpd)で指定できる. booleanであれば--ez (e.g. --ez prefer_extension_decoders TRUE). String配列であれば--esa (e.g. --esa drm_key_request_properties name1,value1)を使って設定することができる.

To play a playlist of samples set the intent’s action to com.google.android.exoplayer.demo.action.VIEW_LIST and use a uri_list string array extra instead of a data URI. For example:

サンプルのプレイリストを再生するにはIntentのアクションcom.google.android.exoplayer.demo.action.VIEW_LISTと文字配列uri_listにデータURIを指定します. 例えば,

adb shell am start -a com.google.android.exoplayer.demo.action.VIEW_LIST \
    --esa uri_list https://a.com/sample1.mp4,https://b.com/sample2.mp4

Supported optional extras for a playlist intent are:

プレイリストのIntentでサポートされているオプションは次の通り:

  • extension_list [String array] Sample type hints. Entries may be empty or one of: mpd, ism, m3u8
  • prefer_extension_decoders, drm_scheme_uuid, drm_license_url and drm_key_request_properties, all as described above
  • extension_list [String array] サンプルタイプのヒント. 内容は空かmpd, ism, m3u8のうちどれかです
  • prefer_extension_decoders, drm_scheme_uuid, drm_license_urldrm_key_request_propertiesそれぞれは上記で説明されています.
2016/10/23

Android: AppShortcut - 要点

! warning ! 
この投稿はAndroid 7.1 Developer Preview1 - App Shortcutの内容をもとにしています. 
今後のバージョンアップで内容が変更されている可能性にご注意ください.

App Shortcutについては下記の投稿もご参考ください.

App Shortcut のバリエーション

App Shortcutには2種類あり, さらにショートカットの状態にも2種類あります.

Static Shortcut(Manifest Shortcut)
リソースファイルで定義される静的なショートカットです.

Dynamic Shortcut
ShortcutManagerのAPIを使って動的に管理されるショートカットです.

さらに, ショートカットはランチャーへ”ピン留め”(Pin)できる機能があり, Static/Dynamic Shortcutどちらもピン留めが可能です.

Pinned Static Shortcut
Static Shortcutからランチャーへピン留めされたショートカットです.

Pinned Dynamic Shortcut
Dynamic Shortcutからランチャーへピン留めされたショートカットです.

App Shortcut のピン留め

ショートカットには更新できるタイプのものと更新できないタイプのものがあります.
Static Shortcutは不変で, アプリのアップデートでのみ変更できます. これは, ピン留めされたStatic Shortcutも同様です.

Action StaticShortcut DynamicShortcut Pinned StaticS. Pinned DynamicS.
Update Ver.UP only always Ver.UP only always

ピン留めされたショートカットは種別を問わずアプリから削除することができず, ユーザ操作を必要とします.

Action StaticShortcut DynamicShortcut Pinned StaticS. Pinned DynamicS.
Delete Ver.UP only always x x

Static Shortcutはアプリから無効化することができません. ショートカットの定義を削除したバージョンにアップデートされるとStatic Shortcutは無効化されます.

Action StaticShortcut DynamicShortcut Pinned StaticS. Pinned DynamicS.
Disable Ver.UP only always Ver.UP only always

ピン留めされたショートカットはバックアップ/リストアや, ショートカットの定義を削除したアプリへのアップデートでも残る性質があります. ショートカットが有効である限りそれに設定されたIntentが飛んでくることを考慮する必要があります.

Action StaticShortcut DynamicShortcut Pinned StaticS. Pinned DynamicS.
Remain via Ver.UP no yes yes(disable) yes

下表は上記をまとめたものです.

Action StaticShortcut DynamicShortcut Pinned StaticS. Pinned DynamicS.
Update Ver.UP only always Ver.UP only always
Delete Ver.UP only always x x
Disable Ver.UP only always Ver.UP only always
Remain via Ver.UP no yes yes(disable) yes

ShortcutManager API

Static Shortcutは不変であるため, アプリがショートカットを管理するのは主にDynamic Shortcutになります. ショートカットを追加, 変更, 削除, 無効化, およびそれをサポートするAPIは次の通りです.

ShortcutManager

disableShortcuts(List shortcutIds, CharSequence disabledMessage)
ピン留めされたショートカットを無効化し, ショートカット選択時のエラーメッセージを指定できます.

getDynamicShortcuts()
すべてのDynamic Shortcutを取得します.

_getManifestShortcuts()
すべてのStatic Shortcutを取得します.

getPinnedShortcuts()
すべてのピン留めされたショートカットを取得します.

removeDynamicShortcuts(List shortcutIds)
引数shortcutIdsのDynamic Shortcutを削除します.

addDynamicShortcuts(List shortcutInfoList)
Dynamic Shortcutを追加します. すでに存在しているショートカットと同じIDのものがある場合は更新されます. このAPIはRate-limitの対象です.

setDynamicShortcuts(List shortcutInfoList)
Dynamic Shortcutを登録します. すでに存在しているショートカットと同じIDのものがある場合は置き換えられます. ピン留めされたショートカットは不変でないものだけが置き換えられます. このAPIはRate-limitの対象です.

updateShortcuts(List shortcutInfoList)
すでに存在するショートカットと同じIDのものを更新します. ピン留めされたショートカットは不変でないものだけが更新できます. このAPIはRate-limitの対象です.

ShortcutInfo

getExtras()
当該ショートカットに設定された, 任意の情報を格納できるextraを取得します.

isDeclaredInManifest()
当該ショートカットが, マニフェストで定義されるStatic Shortcutであるか否かを取得できます.

isDynamic()
当該ショートカットが, Dynamic Shortcutであるか否かを取得できます.

isEnabled()
当該ショートカットが, 有効な状態であるか否かを取得できます.

isImmutable()
当該ショートカットが, 変更できない不変なものであるか否かを取得できます.

isPinned()
当該ショートカットが, ピン留めされたショートカットであるか否かを取得できます.

Shortcut Listの並び順

ショートカットリストはランチャーアイコンに近い方から優先度(rank)の昇順で並べます(これはランチャーアプリの実装に依存します). 例えばNexus Launcherであればリストの並ぶ方向はランチャーアイコンの位置によって変わります.

Shortcutの期限と再利用

ショートカットはユーザに特定のアクションへ素早くアクセスさせるための手段です. それぞれのショートカットはそれを特定するために一意で不変なIDを割り当てられます. このIDはショートカットを登録するアプリが任意に指定できますが, 次の点を考慮し, これを厳守する必要があります.

  • ピン留めされたショートカットに”残る性質”がある
  • バックアップ/リストアで他端末に復元される可能性
  • 古いバージョンで登録した既にサポートしないショートカットが新しいバージョンのアプリに対して実行される

ショートカットに向かないパラメータ

ショートカットはピン留めされると”残ります”. そして, 異なる端末にリストアされる可能性もあります.
例えば, Registration IDのような期限付きの情報をショートカットに紐付けるなどした場合, それが期限切れとなっている可能性を考慮する必要があります.
また, 端末固有の情報(IMEIなど)は異なる端末にリストアされた場合に間違った情報となることに注意が必要です.

ショートカットに登録しておく情報は恒久的に変わらない類のものであれば問題ないのですが, そうでない場合はショートカットの情報が古くなったケースや, 端末の状況が変わりショートカットの情報が正しいものではなくなるケースを考慮したコードを用意しておく必要があります.
そういったコードは, 一般的に起動されるアクティビティのonCreateに記述します.

Dynamic Shortcut IDを無理やりStatic Shortcut IDに

Dynamic Shortcutで使用されているIDを, アプリバージョンアップを経てStatic ShortcutのIDで再利用した場合の仕様は現状記載がありません.
Android7.1 emulatorのNexus Launcherアプリで確認する限り, すでに登録されているDynamic Shortcut IDをStatic Shortcutで上書きしようとしても失敗し, Dynamic/Static Shortcutは両方存在しなくなりました.
事前にDynamic Shortcutをピン留めしていた場合, これはDynamic Shortcutのピン留めショートカットとして振る舞うため無効化が可能な状態になります.

このあたりの動作はLauncherアプリの実装に依存するところもあるでしょうし, そもそもShortcut IDの一意性や永続性を厳守すれば考えなくてもよい問題です.
Shortcut IDは一意に, 意味が変わるようであれば新規IDを払い出し, IDの再利用は避けるのが吉です.

Launcher Applicationの実装

Android7.1の端末であればApp Shortcut機能を持ったランチャーアプリが必ず搭載されているわけではありません. App Shortcutの機能をサポートするかどうか, ピン留めをサポートするか, App Shortcutをどのようなジェスチャーを契機に表示するかなど, そのほとんどがランチャーアプリに依存します. ショートカットのShort labelも必ず表示されるとは限りません.

Shortcutのセキュリティ

他のアプリはあなたのショートカットメタデータにアクセスすることができませんが, ランチャーアプリに限ってはこれにアクセスすることが可能です. そのため, このメタデータにユーザ情報などのセンシティブなデータを含めないようにすべきです.

以上です.