AppleのHTTP Live Streaming Toolsの使い方

# HTTP Live Streaming Toolsとは

[Apple Developers](https://developer.apple.com/)で公開されているHTTP Live Streaming(HLS)の作成や検証用のコマンドラインツール。
Appleが公開している[HTTPライブストリーミングの概要](https://developer.apple.com/jp/documentation/StreamingMediaGuide.pdf)の中にも記載されている。

## メディアストリームセグメンタ

MPEG2トランスポートストリームを入力として、HLSに必要なプレイリストとTSファイルの作成を行う。

## メディアファイルセグメンタ

メディアファイルを入力として、HLSに必要なプレイリストとメディアセグメントファイルの作成を行う。
挙動はほぼメディアストリームセグメンタと一緒だが、入力がエンコーダからのストリームではなく、既存のメディアファイルという点が異なる。

## メディアサブタイトルセグメンタ

HLSで使用出来るWeb Video Text Tracks(WebVTT)形式のサブタイトルセグメントを生成する。

## メディアストリームバリデータ

指定したサーバ上のプレイリスト、代替ストリーム、メディアセグメントファイルを検証し、HLSクライアントと連動するかチェックする。
HLSクライアントで指定できるのは、iPod、iPhone、Apple TV、iPadのみ。

## バリアントプレイリストクリエータ

メディアファイルセグメンタの出力を使用して、各種ビットレートの代替ストリームのプレイリストをリストアップしたマスタプレイリストを作成する。

## メタデータタグジェネレータ

ID3メタデータを生成する。

## HLSレポート

メディアストリームバリデータの出力するjsonファイルを入力として、HLSのレポートをHTML形式で出力する。

# 使い方

[Apple Developer](https://developer.apple.com/download/more/)で検索窓から`live streaming`で検索。
`HTTPLiveStreamingTools_268.dmg`をダウンロードしてインストール。

![スクリーンショット 2017-03-08 10.48.04_m.png](https://qiita-image-store.s3.amazonaws.com/0/43800/578399c9-b352-872c-f6db-47e352f4e27c.png)


## メディアストリームセグメンタ

### オプション

#### -b | -base-url

指定したURLがプレイリスト内に記載されるメディアセグメントファイル名の前に連結される。

#### -t | -target-duration

メディアセグメントファイル1個あたりの秒数を指定する。デフォルトは10秒。
トランスポートストリームの[PES](https://en.wikipedia.org/wiki/Packetized_elementary_stream)中のPTS/DTSをもとに算出される。

#### -u | -receive-data-timeout

データの受信がなくなり停止状態(タイムアウト)になるまでの秒数を指定する。
`0`はタイムアウトなし。

#### -U | -exit-on-receive-data-timeout

`receive-data-timeout`オプションと同時に使うことで、停止ではなくセグメンタの終了に挙動を変更する。

#### -f | -file-base path

指定したパス配下にプレイリストとメディアセグメントファイルが作成される。

#### -p | -program

このオプションを指定することでVOD形式(プレイリストに全セグメントが記載)となる。
`Ctrl + C` でセッションを停止することができる。

#### -i | -index-file

プレイリスト名を変更したい場合に指定する。
デフォルトは `prog_index.m3u8` 。
拡張子には `.m3u8` もしくは `.m3u` が推奨される。

#### -B | -base-media-file-name

メディアセグメントファイル名のベースを変更したい場合に指定する。
デフォルトは `fileSequence` で、これに通番と拡張子が連結される。

#### -s | -sliding-window-entries

プレイリストに残すメディアセグメントファイル数を指定する。
デフォルトは`5`。

#### -S | -start-index-file-count

最初のプレイリスト作成に必要なメディアセグメントファイル数を指定する。
デフォルトは`3`。

#### -I | -initial-sequence-number

メディアセグメントファイルの通番をいくつから開始したいかを指定する。

#### -D | -delete-files

ライブストリーム時にプレイリストで不要となったメディアセグメントファイルを削除する場合に指定する。

#### -M | -metadata-rx-port

メタデータを受け取るTCPポートを指定する。
メタデータの生成および送信はid3taggeneratorを参照。

#### -a | -audio-only

出力を音声ストリーム(AAC/ADTSもしくはMP3)だけにする。

### 使用例

ネットワークアドレス`239.4.1.5:20103`からライブストリームをキャプチャし、`output`配下にプレイリストとメディアセグメントファイルを生成する。
プレイリストに記載するメディアセグメントファイル数は3(`-s 3`オプション)で、古いものは削除(`-D`オプション)される。
```
% mediastreamsegmenter -s 3 -D -f output 239.4.1.5:20103
```

## メディアファイルセグメンタ

### オプション

#### -b | -base-url

指定したURLがプレイリスト内に記載されるメディアセグメントファイル名の前に連結される。

#### -f | -file-base

指定したパス配下にプレイリストとメディアセグメントファイルが作成される。

#### -t | -target-duration

メディアセグメントファイル1個あたりの秒数を指定する。デフォルトは10秒。
算出には入力ファイルのPTS/DTSが使われる。

#### -F | -meta-file

指定したファイルを読み込み、その内容を各メディアセグメントファイルにメタデータとして書き込む。
指定したファイルが存在しない場合はメタデータは書き込まれない。

#### -y | -meta-type

メタデータの種類を指定する。
`picture | text | id3` から指定可能。
`picture` を指定した場合、画像の形式はJPEGかPNGを想定。
`id3` を指定した場合、完全なID3フレームを想定。
音声のみのストリームに画像を入れるには、 `picture` を指定する。

#### -i | -index-file

プレイリスト名を変更したい場合に指定する。
デフォルトは `prog_index.m3u8` 。
拡張子には `.m3u8` もしくは `.m3u` が推奨される。

#### -B | -base-media-file-name

メディアセグメントファイル名のベースを変更したい場合に指定する。
デフォルトは `fileSequence` で、これに通番と拡張子が連結される。

#### -I | -generate-variant-plist

バリアントプレイリストクリエータに必要なplistを出力する。
出力されるplistファイル名は、入力ファイルの拡張子を `.plist` に置き換えたものとなる。

#### -a | -audio-only

出力を音声ストリーム(AAC/ADTSもしくはMP3)だけにする。

#### -A | -video-only

出力を映像のみのトランスポートストリームだけにする。

### 使用例

メディアセグメントファイル1個あたりの秒数を2秒、ベースURLを `http://sample.com` 、出力先を `output` に指定して実行

```
% mediafilesegmenter -t 2 -b http://sample.com -f output -I sample01.mp4
Mar  8 2017 15:23:54.099: Using floating point is not backward compatible to iOS 4.1 or earlier devices
Mar  8 2017 15:23:54.100: Processing file /Users/hapoon/movie/sample01.mp4
Mar  8 2017 15:23:54.136: Finalized /Users/hapoon/movie/output/fileSequence0.ts
Mar  8 2017 15:23:54.136: segment bitrate  1.65 Mbits/sec is new max
Mar  8 2017 15:23:54.139: Finalized /Users/hapoon/movie/output/fileSequence1.ts
Mar  8 2017 15:23:54.139: segment does not contain sync frame
Mar  8 2017 15:23:54.142: Finalized /Users/hapoon/movie/output/fileSequence2.ts
Mar  8 2017 15:23:54.372: segment does not contain sync frame
Mar  8 2017 15:23:54.373: average bit rate is  1.23 Mbits/sec - max file bit rate is  2.67 Mbits/sec
```

## メディアサブタイトルセグメンタ

### オプション

#### -b | -base-url

指定したURLがプレイリスト内に記載されるメディアセグメントファイル名の前に連結される。

#### -t | -target-duration

字幕ファイル1個あたりの秒数を指定する。デフォルトは60秒。

#### -f | -file-base

指定したパス配下に字幕ファイルとプレイリストが作成される。

#### -i | -index-file

プレイリスト名を変更したい場合に指定する。
デフォルトは prog_index.m3u8 。
拡張子には .m3u8 もしくは .m3u が推奨される。

#### -B | -base-media-file-name

メディアセグメントファイル名のベースを変更したい場合に指定する。
デフォルトは fileSequence で、これに通番と拡張子が連結される。

#### -s | -subtitle-variant

字幕マスタプレイリスト名を変更したい場合に指定する。
デフォルトは `subtitle_media.m3u8`

### 使用例

SRT形式の字幕ファイルからWebVTTの字幕ファイルを `subtitle` 配下に作成。

```
% mediasubtitlesegmenter -f subtitle -t 2 sample01.srt
Mar  8 2017 17:58:05.655: Finalized subtitle/fileSequence0.webvtt
Mar  8 2017 17:58:05.655: segment bitrate 424.00 bits/sec is new max
Mar  8 2017 17:58:05.655: Finalized subtitle/fileSequence1.webvtt
Mar  8 2017 17:58:05.655: Finalized subtitle/fileSequence2.webvtt
Mar  8 2017 17:58:05.655: Finalized subtitle/fileSequence3.webvtt
Mar  8 2017 17:58:05.656: Finalized subtitle/fileSequence4.webvtt
Mar  8 2017 17:58:05.656: Finalized subtitle/fileSequence5.webvtt
Mar  8 2017 17:58:05.656: Finalized subtitle/fileSequence6.webvtt
Mar  8 2017 17:58:05.656: Finalized subtitle/fileSequence7.webvtt
Mar  8 2017 17:58:05.656: Finalized subtitle/fileSequence8.webvtt
Mar  8 2017 17:58:05.656: Finalized subtitle/fileSequence9.webvtt
Mar  8 2017 17:58:05.657: Finalized subtitle/fileSequence10.webvtt
Mar  8 2017 17:58:05.657: average bit rate is 311.00 bits/sec - max file bit rate is 424.00 bits/sec
```

## メディアストリームバリデータ

### オプション

#### -d | --device

接続で使用する端末のユーザーエージェントを指定。
`ipod | iphone | atv | ipad` のいずれかを指定可能。

#### -O | --validation-data-path

指定したパスに検証結果をJSON形式で保存する。
HLSレポートの入力となる。

#### -p | --parse-playlist-only

プレイリストのパースだけする場合に使用する。

#### -t | --timeout

検証のタイムアウト秒数を指定する。
指定しない場合のデフォルト秒数は300秒。

#### -v | --version

バージョンを表示する。

#### -V | --verbose

詳細な表示をする。
デフォルトはオフ。

### 使用例

タイムアウト秒数を10秒でプレイリストを検証し、結果を `output/validate.json` に保存する

```
% mediastreamvalidator -t 10　-O output/validate.json https://sample.com/playlist/123.m3u8
mediastreamvalidator: Version 1.2(160525)

[/playlist/123.m3u8] Started root playlist download
[/playlist/123.m3u8] Started media playlist download
[/playlist/123.m3u8] All media files delivered, waiting until next playlist fetch
[/playlist/123.m3u8] All media files delivered, waiting until next playlist fetch
[/playlist/123.m3u8] All media files delivered, waiting until next playlist fetch
[/playlist/123.m3u8] All media files delivered, waiting until next playlist fetch
[/playlist/123.m3u8] All media files delivered, waiting until next playlist fetch
[/playlist/123.m3u8] All media files delivered, waiting until next playlist fetch

--------------------------------------------------------------------------------
https://sample.com/playlist/123.m3u8
--------------------------------------------------------------------------------
Processed 15 out of 15 segments
Average segment duration: 2.000000
Total segment bitrates (all discontinuities): average: 3353.97 kb/s, max: 4643.60 kb/s


Discontinuity: sequence: 0, parsed segment count: 15 of 15, duration: 30.000 sec, average: 3353.97 kb/s, max: 4643.60 kb/s
Track ID: 3
Track ID: 1
Video Codec: avc1
Video profile: Main
Video level: 4.1
Video resolution: 1024x576
Video average IDR interval: 1.000000, Standard deviation: 0.000000
Video frame rate: 29.985
Track ID: 2
Audio Codec: AAC-LC
Audio sample rate: 44100 Hz
Audio channel layout: Stereo (L R)
```

## バリアントプレイリストクリエータ

### オプション

#### -o | -output-file

マスタプレイリストの出力ファイル名を指定する。

#### -no-codecs-tags

マスタプレイリストの `#EXT-X-STREAM-INF` に `CODECS` タグを追加しない。

#### -no-resolution-tags

マスタプレイリストの `#EXT-X-STREAM-INF` に `RESOLUTION` タグを追加しない。

### 使用例

3種類の解像度(lo,mid,hi)のプレイリストからマスタプレイリスト `all.m3u8` を生成する。
```
% variantplaylistcreator -o all.m3u8 http://sample.com/lo/prog_index.m3u8 lo.plist http://sample.com/mid/prog_index.m3u8 mid.plist
     http://sample.com/hi/prog_index.m3u8 hi.plist
```

## メタデータタグジェネレータ

### オプション

#### -o | -output-file

生成したID3タグを出力するパスを指定する。

#### -a | -output-address

生成したID3タグを送信するIPアドレスとポート番号を `<addr>:<port>` の形式で指定する。
mediastreamsegmenterはここで指定したポートからID3タグ情報を受け取る。

#### -r | -repeat

mediastreamsegmenterで各セグメントにID3タグを繰り返し埋め込む際に指定する。

#### -t | -text

指定のテキストをテキストフレームとして挿入する。

#### -text-type

`-text`オプションの後で使用された際に、テキストID3タグを生成する時にどのフレームIDで使用されるかを指定する。
省略した場合は `TXXX`が使用される。

#### -title

指定のテキストをタイトルフレームとして挿入する。
`-text <string> -text-type TIT2`と同義。

#### -u | -url

指定のURLをURLフレームとして挿入する。

#### -url-type

`-url`オプションの後で使用された際に、URLID3タグを生成する時にどのフレームIDで使用されるかを指定する。
省略した場合は `WXXX`が使用される。

#### -i | -picture

指定の画像をID3フレームとして挿入する。
JPEG画像とPNG画像がサポートされている。

#### -picture-type

`-picture`オプションの後で使用された際に、画像ID3タグを生成する時にどのフレームIDで使用されるかを指定する。
指定できる値は整数値。
指定できる値のリストは[こちら](http://id3.org/id3v2.3.0#Attached_picture)を参照。
省略した場合は、`16 (Movie/video screen capture)`が使用される。

#### -plist

指定されたApple property list(.plist)を含んだID3フレームを挿入する。

#### -generic-object

指定したバイナリーデータを含んだID3フレームを挿入する。

#### -generic-object-type

`-generic-object`オプションの後で使用された際に、総称オブジェクトID3フレームを生成する時に使用されるMIME/Typeを指定する。
省略した場合は、`application/octet-stream`が使用される。

#### -d | -description

事前に指定したテキスト、URL、画像、plist、総称オブジェクトフレームの説明を指定できる。
ID3フレームIDが`TXXX`、`WXXX`、`APIC`、`GEOB`に対して適用できる。

### 使用例

```
% id3taggenerator -o out.id3 -t "abcde" -d "abcde desc" -t "12345" -d "12345 desc"
```

出力したout.id3をバイナリエディタで開くと
<img width="524" alt="スクリーンショット 2017-03-09 10.40.44.png" src="https://qiita-image-store.s3.amazonaws.com/0/43800/bbb47020-ecfa-485f-9b6b-cd77c9fe7269.png">


## HLSレポート

### オプション

#### -i | --id

出力結果のHTMLにOverviewテーブルにデータIDを表示する。

#### -p | --pl

#### -o | --output

出力するHTMLファイル名を指定する。
デフォルトは入力となるjsonファイルの拡張子をhtmlに変換したもの。

#### -V | --verbose

下記のような詳細情報を出力に追加する。

![スクリーンショット 2017-03-08 12.54.43_m.png](https://qiita-image-store.s3.amazonaws.com/0/43800/762b5e75-ee9a-8649-7e8d-e7d20773916f.png)


### 使用例

カレントディレクトリにあるvalidate.jsonを入力として、詳細情報込みでレポートを `report/validate.html` として出力する。
```
% hlsreport.py -V -o report/validate.html validate.json
```

出力されたHTMLをブラウザで開くと下記のようなレポートが表示される。

![スクリーンショット 2017-03-08 12.44.41_m.png](https://qiita-image-store.s3.amazonaws.com/0/43800/391516e3-727d-fa79-2551-3b7fdfae77eb.png)

# 参照

- https://developer.apple.com/jp/documentation/NetworkingInternet/Conceptual/StreamingMediaGuide/RevisionHistory.html#//apple_ref/doc/uid/TP40008332-CH99-SW1
- https://developer.apple.com/library/content/documentation/AudioVideo/Conceptual/HTTP_Live_Streaming_Metadata_Spec/Introduction/Introduction.html#//apple_ref/doc/uid/TP40010435-CH1-DontLinkElementID_11
- http://id3.org/id3v2.3.0