Hisui では JSON 形式のレイアウトファイルを使用することでより細かな合成の設定が可能です。 レイアウトファイルでは合成する音声/映像の制御や、合成時の映像の場所など自由に設定することができます。 ここではレイアウトで使用できるパラメータやレイアウト例について記載します。
- X の倍数に丸める: 値が X の倍数になるよう数値を小さくなる方向に変更します(変更しなくてよい場合はしません)。
--layout オプションでレイアウト設定を指定します。 レイアウト設定は JSON ファイルを指定して利用します。
実行コマンド例:
hisui --layout layout.json
{
"audio_sources": [
"./archive-*.json"
],
"audio_sources_excluded": [
"./archive-7VZRQBE3ZS5ES9BV5VGVF4TSTW.json"
],
"video_layout": {
"grid": {
"video_sources": [
"./archive-*.json"
]
}
},
"trim": true,
"format": "webm",
"resolution": "640x360",
"bitrate": 1000
}
レイアウトに設定しているパラメータの説明
このレイアウトはマス目状に映像を配置して合成します。 合成結果はスクリーンショットのようになります。
それぞれのパラメータについて以下に説明します。
audio_sources: 格納されているファイル全てを相対パスで指定しますaudio_sources_excluded: ファイルの中から音声を入れないファイルを指定しますvideo_layout: 映像レイアウトをこの中に指定しますgrid: 分かりやすい名称をつけてレイアウトを指定しますvideo_sources: 合成する映像ファイルを全て指定します
trim: 音声も映像もない時に trim を有効にするかどうか指定しますformat: 出力するフォーマットを指定しますresolution: 出力する映像のサイズを指定しますbitrate: 出力する映像のビットレートを指定します
Hisui レイアウトは Composing Video Recordings using Twilio Programmable Video - Twilio に準じます。
Hisui のレイアウトでは audio_sources, audio_sources_excluded, Region(後述) 内の video_sources, video_sources_excluded に、Sora の archive-*.json のパス/パターンを指定します。
レイアウトで使用可能な設定パラメータについて以下に記載します。
音声のソースとして用いる archive-*.json のパスの配列を指定します。相対パスの指定も可能です。 パスは JSON ファイルのあるパスからの相対パスを探します。
* をワイルドカードとして利用することができます。
* を使用する場合は Sora の録画データと同じディレクトリにレイアウトファイルがあること、Sora の録画データ以外のファイルが無いようにする必要があります。
audio_sources のうち除外するソースのパターンの配列を指定します。
* をワイルドカードとして利用することができます。
* を使用する場合は Sora の録画データと同じディレクトリにレイアウトファイルがあること、Sora の録画データ以外のファイルが無いようにする必要があります。
目標 bitrate を指定します。
video の bitrate 指定に利用しています。
0 ないし未定義(キーがない場合)は適宜計算しています。
出力フォーマットを指定します。 webm か mp4 を指定することができます。
映像の解像度を文字列で {幅}x{高さ} の形式で指定します。(例: "640x480", "1280x720") 幅、高さの最小値は 16 です。
4 の倍数に丸めています。 最大は 3840x3840 まで許容しています。
音声、映像のソースのすべてが存在しない時間間隔について、
false であれば 0 時間始まりのもののみ、true の場合はすべてについて出力からカットします。
映像の配置を指定します。
Region 名(string) と Region の内容(object) の複数個の組から構成されます。
Region は映像を配置するスペースです。その内部を Grid で指定される区画に区切られます。区切られた部分を Cell と呼びます。
Grid の行と列の最大値は max_columns と max_rows によって指定されます。
ただし、 該当キーがない場合と 0 の場合は未指定となります。
Twilio では 0 は許可していませんが、 Hisui では 0 を未指定と同様に扱っています。
cells_excluded と reuse (後述) を考慮した最大同時ソース数が収まるように、かつ行と列の数がなるべく同じになるように、行と列の数を決定します。
ただし、行の数は列の数よりも 1 大きくても問題ありません。
cells_excluded と reuse (後述) を考慮した最大同時ソース数よりも指定されている数が等しいか大きい場合は、最大同時ソース数行 x1 列 ないし 1 行 x 最大同時ソース数列の Grid となります。
それよりも大きい場合は、max_columns 行ないし max_rows列となり、列ないし行が必要なだけ追加されます。
cells_excluded と reuse (後述) を考慮した最大同時ソース数よりも max_columns x max_rows が等しいか小さい場合は、max_columns 行 x max_rows 列となります。
max_columns > max_rows の場合、
max_columns のほうが最大同時ソース数よりも大きいか等しい場合は 最大同時ソース数行 x1 列 となります。
そうでない場合は max_columns 行 ソースが収まる 列 となります。
max_columns <= max_rows の場合も、行と列が入れ替わった形で同様となります。
Region は Grid によって Cell に分割されます。Cell 間には枠線が 2 pixel 配置されます。
Region のサイズ(width ないし height[後述]) が、動画のサイズ(resolution で決定される幅ないし高さ)と等しい場合は、Region の両端に枠線が入りません。そうでない場合は枠線が入ります。
各 Cell のサイズは 4 の倍数となります。
このため、たとえば 240x160 の動画だけの Region についてそれより大きな(640x480 など)ベースに対して配置する場合、スケールを発生させないようにするには 244x164 の Region を指定する必要があります。
これらを考慮して 1 つの Cell のサイズがなるべく大きくなるように Cell のサイズを決定します。
Cell には次の状態が存在します:
- Fresh: まだ利用されていない状態
- Used: 現在利用されている状態
- Idel: 以前利用されていたが現在は利用されていない状態
- Excluded:
cells_excludedで指定された Cell で利用されることはありません
一番左上の Cell の index を 0 として、左から右、上から下の順で index が振られた Cell のうち、映像を表示しません index の配列を指定します。
Region の高さを指定します。キーがない場合と 0 の場合は y_pos から決定されます (resolution.height - y_pos)。 16 未満の場合、resolution.height からはみ出る場合はエラーとなります。
2 の倍数に丸めています。
前述
前述
Cell へのソースの配置の仕方を指定します。
video_sources での指定の最初から順に配置していきます。(connection_id 対応などすると変わる可能性があります)
none: Fresh な Cell にのみ新しいソースを配置しますshow_oldest: Fresh な Cell に加えて Idle な Cell にも 新しいソースを配置しますshow_newest: さらに, Used な Cell の中で 新しいソースよりも Cell の持つソースの開始時間が前の Cell のうち、最小の終了時間のソースを持つ Cell に新しいソースを配置します
映像のソースとして用いる archive-*.json のパスの配列を指定します。相対パスの場合は、レイアウト設定を指定します。 JSON ファイルのあるパスからの相対パスを探すようになっています。
* をワイルドカードとして利用できます。
* を使用する場合は Sora の録画データと同じディレクトリにレイアウトファイルがあること、Sora の録画データ以外のファイルが無いようにする必要があります。
video_sources のうち除外するソースのパターンの配列を指定します。
* をワイルドカードとして利用できます。
* を使用する場合は Sora の録画データと同じディレクトリにレイアウトファイルがあること、Sora の録画データ以外のファイルが無いようにする必要があります。
Region の幅を指定します。 キーがない場合と 0 の場合は x_pos から決定されます (resolution.width - x_pos)。 16 未満の場合、resolution.width からはみ出る場合はエラーとなります。
2 の倍数に丸めています。
Region の左上の位置の x を指定します。キーがない場合は 0。[0, resolution.width] の範囲でない場合はエラーとなります。
Region の左上の位置の y を指定します。キーがない場合は 0。[0, resolution.height] の範囲でない場合はエラーとなります。
Region の z 軸での位置を指定する。キーがない場合は 0。[-99, 99] の範囲でない場合はエラーとなります。
同じ z_pos の Region が複数あった場合にどういう順序で描画されるかは未定義です。
archive-*.json 中の filename, file_path の順に WebM ファイルを探索します。
どちらについても、
- 絶対パスの場合: その絶対パスのみを探索します
- 相対パスの場合: まずレイアウト設定ファイルのパスからの相対パスを探索し、見つからない場合レイアウト設定ファイルのパスに、相対パスの basename があるかどうか探索します
合成する時間は archive-*.json の start_time, stop_time を利用します。プログラムでは double としてパースしています。
video_sources で定義された順序に、video_sources_excluded, reuse を考慮して描画されます。
connection_id はパースしているがソースの同一性の判定には利用していません。