iMac MiniでのApple Spatial Video変換

進行過程

iMac Mini M2Pro装置を購入してSpatial Video動画を製作してみました。

spatialプログラムのインストール

すでに他の開発者が配布したSpatial Video製作ツールがあるので、それを利用してSpatial Videoを製作してみました。
ツールのインストールはHomeBrewを利用して行います。
https://blog.mikeswanson.com/spatial/

• homebrew設置

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

• spatialプログラムのインストール

brew install spatial

ちなみに、上記のbrewに対するプログラムのインストールの試みはubuntuでもしてみましたし、Vmware WorkstationにインストールしたMac OSでも行ってみました。

• Linux
  https://linux.how2shout.com/how-to-install-brew-ubuntu-20-04-lts-linux/ ガイドに従ってubuntuにlinuxbrewをインストールした後、上記コマンドを実行したが、spatialというプログラムが登録されていないというメッセージが表示されます。
• VMWare Workstation MacOS Image
  VMWare WorkstationにインストールしたMac OSでHomebrewをインストールしてspatialプログラムをインストールしようとした場合、このプログラムはarm cpuでのみインストールできるというメッセージが表示され、インストールが失敗します。

また、arm cpuがインストールされたMac OS環境でのみSpatial Video製作が可能だということを示しています。

Spatial動画の作成過程で提起された問題点

今回の目的は、左目と右目用に撮影したVR180動画の2つをMV-HEVC動画に変換し、Apple Vision ProのImmersive Playerで正常に再生させることです。
左目と右目用にそれぞれ撮影した elp_05_left.mp4 ファイルと elp_05_right.mp4 ファイルをあらかじめ準備します。

hev1コーデックイシュー

上記のプログラム設置後、プログラムのSpatialビデオ製作形式に合わせてコマンドを作成しました。

spatial make -i elp_05_left.mp4 -i elp_06_right.mp4 -o elp_left_eye.mov --cdist 63.0 --hfov 180.0 --hadjust 0.0 --hero left --primary left --projection halfEquirect

上記のコマンドを実行すると、AVFoundationは「hev1」で制作された動画はサポートしないというメッセージが表示されます。
ffmpegを利用して動画を「hvc1」コーデックに変換するようにというメッセージも表示されます。

a1234@1234deMac-mini result % spatial make -i elp_05_left.mp4 -i elp_06_right.mp4 -o elp_left_eye.mov --cdist 63.0 --hfov 180.0 --hadjust 0.0 --hero left --primary left --projection halfEquirect
 Left input: elp_05_left.mp4 (flat)
Right input: elp_06_right.mp4 (flat)
     Output: elp_left_eye.mov (spatial/mv-hevc)

The input video is tagged with the 'hev1' codec, and the AVFoundation framework isn't compatible with that format. If this process fails, try re-tagging the input video with 'hvc1'. This can be done without re-encoding using ffmpeg:

ffmpeg -i "/Users/a1234/Documents/work/result/elp_05_left.mp4" -c copy -tag:v hvc1 output.mov

The input video is tagged with the 'hev1' codec, and the AVFoundation framework isn't compatible with that format. If this process fails, try re-tagging the input video with 'hvc1'. This can be done without re-encoding using ffmpeg:

ffmpeg -i "/Users/a1234/Documents/work/result/elp_06_right.mp4" -c copy -tag:v hvc1 output.mov
spatial/VideoProcessor.swift:121: Fatal error: Can't apply output settings
zsh: trace trap  spatial make -i elp_05_left.mp4 -i elp_06_right.mp4 -o elp_left_eye.mov 63.0

これに基づいて追加で確認したところ、AVFoundationではH264の場合はavc1、H265の場合はhvc1をサポートします。
つまり、Spatial Videoを制作する前に、まず動画を上記のエンコードのいずれかに変換する必要があります。

• H264 avc1 に変換するコマンド

ffmpeg -i elp_05_left.mp4 -c:v libx264 -c:a copy elp_05_left4.mp4
ffmpeg -i elp_06_right.mp4 -c:v libx264 -c:a copy elp_06_right4.mp4

• H265 hvc1に変換するコマンド

ffmpeg -i elp_05_left.mp4 -c:v libx265 -tag:v hvc1 -c:a copy elp_05_left3.mp4
ffmpeg -i elp_06_right.mp4 -c:v libx265 -tag:v hvc1 -c:a copy elp_06_right3.mp4

colorspaceイシュー

上記の動画をH265 hvc1コーデックに変換し、spatial videoの作成を試みましたが、新しいエラーが表示されました。

ffmpeg -i elp_05_left.mp4 -c:v libx265 -tag:v hvc1 -c:a copy elp_05_left3.mp4
ffmpeg -i elp_06_right.mp4 -c:v libx265 -tag:v hvc1 -c:a copy elp_06_right3.mp4
spatial make -i elp_05_left3.mp4 -i elp_06_right3.mp4 -o elp_left_eye_from_hevc.mov --cdist 63.0 --hfov 180.0 --hadjust 0.0 --hero left --primary left --projection halfEquirect

 Left input: elp_05_left3.mp4 (flat)
Right input: elp_06_right3.mp4 (flat)
     Output: elp_left_eye_from_hevc.mov (spatial/mv-hevc)
spatial/VideoProcessor.swift:121: Fatal error: Can't apply output settings
zsh: trace trap  spatial make -i elp_05_left3.mp4 -i elp_06_right3.mp4 -o --cdist 63.0

H265 hvc1コーデックに問題があると思い、H264avc1コーデックに変換した後、再びspatial videoの作成を試みてみました。

ffmpeg -i elp_05_left.mp4 -c:v libx264 -c:a copy elp_05_left4.mp4
ffmpeg -i elp_06_right.mp4 -c:v libx264 -c:a copy elp_06_right4.mp4

spatial make -i elp_05_left4.mp4 -i elp_06_right4.mp4 -o elp_left_eye_from_h264.mov --cdist 63.0 --hfov 180.0 --hadjust 0.0 --hero left --primary left --projection halfEquirect

H265 hvc1と同じエラーが表示されます。

 Left input: elp_05_left4.mp4 (flat)
Right input: elp_06_right4.mp4 (flat)
     Output: elp_left_eye_from_h264.mov (spatial/mv-hevc)
spatial/VideoProcessor.swift:121: Fatal error: Can't apply output settings
zsh: trace trap  spatial make -i elp_05_left4.mp4 -i elp_06_right4.mp4 -o --cdist 63.0

一番初期にはエラーの原因をspatialビデオ製作のためには別途のカメラで動画を撮影しなければならないのではないかと考えてみました。
しかし、以前に受け取ったiStock-138879858.mov(300M)の場合には、Spatialコマンドが正常に再生されるのを見て、ビデオのフォーマットに問題があることを知りました。

iStock-138879858.mov 右と左目用ビデオに同じように指定し、Spatialビデオ作成コマンドが成功しました。

spatial make -i iStock-1388879858.mov -i iStock-1388879858.mov -o outuput.mov --cdist 63.0 --hfov 180.0 --hadjust 0.0 --hero left --primary left --projection halfEquirect

elp_05_left4.mp4 / elp_06_right4.mp4 動画のフォーマットに何が問題なのか考えてみました。

ffprobeで確認したiStock-1388879858.movファイルの情報

Input #0, mov,mp4,m4a,3gp,3g2,mj2, from 'iStock-1388879858.mov':
  Metadata:
    major_brand     : qt  
    minor_version   : 0
    compatible_brands: qt  
    creation_time   : 2022-04-01T04:11:54.000000Z
    com.apple.quicktime.displayname: 4KC
    com.apple.quicktime.title: 4KC
  Duration: 00:00:51.10, start: 0.000000, bitrate: 62917 kb/s
  Stream #0:0[0x1](und): Video: h264 (High) (avc1 / 0x31637661), yuv420p(tv, bt709, progressive), 3840x2160 [SAR 1:1 DAR 16:9], 62762 kb/s, 30 fps, 30 tbr, 3k tbn (default)
      Metadata:
        creation_time   : 2022-04-01T04:11:54.000000Z
        handler_name    : Core Media Video
        vendor_id       : [0][0][0][0]
        encoder         : H.264
        timecode        : 00:00:00:00
  Stream #0:1[0x2](und): Data: none (tmcd / 0x64636D74) (default)
      Metadata:
        creation_time   : 2022-04-01T04:11:54.000000Z
        handler_name    : Core Media Time Code
        timecode        : 00:00:00:00

ffprobeで確認した elp_06_right.mp4 ファイルの情報

Input #0, mov,mp4,m4a,3gp,3g2,mj2, from 'elp_06_right.mp4':
  Metadata:
    major_brand     : isom
    minor_version   : 512
    compatible_brands: isomiso2mp41
    encoder         : Lavf60.16.100
  Duration: 00:00:37.90, start: 0.000000, bitrate: 1488 kb/s
  Stream #0:0[0x1](und): Video: hevc (Main) (hev1 / 0x31766568), yuv420p(tv, bt470bg/unknown/unknown, progressive), 3840x2160 [SAR 1:1 DAR 16:9], 1485 kb/s, 30 fps, 30 tbr, 15360 tbn (default)
      Metadata:
        handler_name    : VideoHandler
        vendor_id       : [0][0][0][0]
        encoder         : Lavc60.31.102 hevc_nvenc

• 最初に発見した違いは、iStock-138879858.movの場合、Stream Metadataが「encoder:H.264」でelp_06_right.mp4の場合「encoder:Lavf60.16.100」となっていることでした。
  メタデータの表示形式に問題がありそうなので、ファイルのEncoderメタデータを変換してみました。

ffmpeg -i elp_06_right.mp4 -c:v libx264 -c:a aac -metadata encoding_tool="H.264" -metadata:s:v:0 encoder="H.264" elp_06_right1.mp4

変換されたファイルを利用してSpatialビデオ作成コマンドを再実行してみましたが、以前と同じエラーが出力され、失敗しました。

• 次に発見した違いは、elp_06_right.mp4 ファイルの場合、Data Streamがないことでした。
  それでffmpegでelp_06_right.mp4ファイルにData Streamを追加してからもう一度試してみました。

ffmpeg -i elp_06_right.mp4 -map 0 -c:v libx264 -c:a copy -timecode 00:00:00:00 -metadata:s:v:0 encoder="H.264" -metadata:s:1 creation_time="2022-04-01T04:11:54.000000Z" -metadata:s:1 handler_name="Core Media Time Code" -metadata:s:1 timecode="00:00:00:00" elp_06_right2.mp4

しかし、Data Streamが追加されたファイルの場合も、やはり以前と同じエラーが出力され、Spatialビデオの作成が失敗しました。

• 次に発見した違いはcolorspaceの違いでした。
  どのビデオについてspatial動画の制作が可能なのか正確に確認するために、spatialプログラムを利用してすでに制作されたSpatialサンプル動画を右目と左目用動画に分離した後、情報を確認してみました。

spatial export -i spatial_test.mov  -o left.mov -o right.mov 

ffprobeで確認したleft.movの情報

Input #0, mov,mp4,m4a,3gp,3g2,mj2, from 'left.mov':
  Metadata:
    major_brand     : qt  
    minor_version   : 0
    compatible_brands: qt  
    creation_time   : 2024-08-24T03:48:36.000000Z
  Duration: 00:00:02.00, start: 0.000000, bitrate: 161 kb/s
  Stream #0:0[0x1](und): Video: hevc (Main) (hvc1 / 0x31637668), yuv420p(tv, bt709, progressive), 1920x1080, 153 kb/s, 30 fps, 30 tbr, 600 tbn (default)
      Metadata:
        creation_time   : 2024-08-24T03:48:36.000000Z
        handler_name    : Core Media Video
        vendor_id       : [0][0][0][0]
        encoder         : HEVC

elp_06_right.mp4のメタデータと比較してみるとあまり差がなく、ただしcolorspaceがyuv420p(tv, bt709, progressive)に設定されています。
iStock-1388879858.movの場合もcolorspaceはyuv420p（tv、bt709、progressive）に設定されています。
elp_06_right.mp4 の場合のみyuv420p (tv, bt470bg/unknown/unknown, progressive) と異なります。
それで、colorspaceに問題があると判断し、colorspaceをbt709に変換した後、spatialビデオ変換を試みてみました。

ffmpeg -i elp_05_left.mp4 -vf "colormatrix=bt601:bt709" -pix_fmt yuv420p -colorspace bt709 -color_primaries bt709 -color_trc bt709 -c:v libx265 -tag:v hvc1 -c:a copy elp_05_left3.mp4
ffmpeg -i elp_06_right.mp4 -vf "colormatrix=bt601:bt709" -pix_fmt yuv420p -colorspace bt709 -color_primaries bt709 -color_trc bt709 -c:v libx265 -tag:v hvc1 -c:a copy elp_06_right3.mp4
spatial make -i elp_05_left3.mp4 -i elp_06_right3.mp4 -o elp_left_eye_from_hevc.mov --cdist 63.0 --hfov 180.0 --hadjust 0.0 --hero left --primary left --projection halfEquirect

結局、colorspaceを変換したビデオを利用してspatialビデオの作成が成功しました。

結論

上記でテストしたencodingタグの設定、Data Streamの追加などは不要なもので、colorspaceさえ変更すればspatialビデオの作成が可能だということを確認することができました。
総合するとspatial コマンドを実行するためには、左右目用動画が次の条件を満たす必要があります。

• ビデオコーデックは、H265 hvc1またはH264 avc1に設定する必要があります。
• colorspaceはbt709に設定する必要があります。

上記の条件を満たさない場合は、ffmpegを利用して変換を行う必要があります。

変換コマンドの実例(コーデックをH265 hvc1に、colorspaceをbt709に変換するffmpegコマンド)

ffmpeg -i elp_05_left.mp4 -vf "colormatrix=bt601:bt709" -pix_fmt yuv420p -colorspace bt709 -color_primaries bt709 -color_trc bt709 -c:v libx265 -tag:v hvc1 -c:a copy elp_05_left3.mp4

spatialコマンドの利用方法

spatialコマンドの詳細な説明は、次のページを参照してください。
https://blog.mikeswanson.com/spatial_docs/

私たちの場合、spatialビデオを製作することが目的なので、spatialコマンドのmakeパラメータだけに注目すればいいです。

• 2つの一般動画を合成してspatialビデオを作成する例題

spatial make -i elp_05_left3.mp4 -i elp_06_right3.mp4 -o elp_left.mov --cdist 19.24 --hfov 63.4 --hadjust 0.02 --hero left--primary left --projection rect

• 2つの180vr動画を合成してspatialビデオを作成する例題

spatial make -i elp_05_left3.mp4 -i elp_06_right3.mp4 -o elp_left.mov --cdist 63.0 --hfov 180.0 --hadjust 0.0 --hero left --primary left --projection halfEquirect

• 2つの360vr動画を合成してspatialビデオを作成する例題

spatial make -i elp_05_left3.mp4 -i elp_06_right3.mp4 -o elp_left.mov --cdist 63.0 --hfov 360.0 --hadjust 0.0  --hero left --primary left --projection equirect

上記変換コマンドで利用したパラメータ値は開発者が推薦した値であり、実際の適用時には状況に合わせて変更されることがあります。(特に--cdist、--hadjustパラメータは2つのカメラの位置によって異なります。)

spatialコマンドの主要パラメータ

spatialコマンドを利用してSpatial動画の作成時に特に注目すべきパラメータは以下の通りです。

--cdist – これは、ビデオをキャプチャするために使用された 2 つのカメラ レンズの中心間距離（ミリメートル単位）を表します。 この値は小数点を含めることができますが、単位はなく、たとえば 19.24 のようになります。 カメラの距離を知っている場合は、含める必要があります。

--hfov – これは、ビデオ キャプチャの水平視野角を図単位で示します。 たとえば、63.4です。 水平視野角を知っている場合は含める必要があります。 この値は必須であり、ビデオがApple Photosから「SPATIAL」にリストされるには--cdistまたは--hadjustのいずれかまたは両方が必要です。

--hadjust – これは水平差の調整で、再生中に左目及び右目のフレームに適用すべき重なりの量(-1.0から1.0)を反映します。 互換性のあるプレーヤーでは、この値がフレーム内の深さに影響を与える必要があります。 正の値は明らかな深さを増加させ、負の値は深さを減らします。

--projection - これは、ビデオのプロジェクション タイプを指定します。 iPhone 15 Proのような標準ビデオの場合、この値は直線形(rect)です。 他の値には、球形、半球形、魚眼レンズがあります。

--hero – これは、空間認識プレーヤーで再生されるとき、「ヒーロー」または最もよく見えるべき目(左または右)を設定します。 例えば、サムネイルやUI要素がビデオの単眼鏡バージョンを表示する必要があるとき、この英雄の目を選択して再生することができます。 これは、標準の 2D ビデオ プレーヤーでどのような目が表示されるかに影響を与えません。

--primary – これは、標準の非空間認識の2Dビデオプレーヤーで再生される目(左または右)を決定します。 MV-HEVCファイルは、2つ以上のビデオレイヤーを含み、標準HEVCビデオを再生するすべてのビデオプレーヤーは、最初のレイヤーだけを再生し、残りは無視します。 この設定は、ビデオ ファイルの最初のレイヤーにどの目がエンコードされるかを決定します。 iPhone 15 Pro ではこの設定が一般的に最も高い品質のイメージを持ったカメラと一致します（これはiPhone 15 Proの一方向では右であり、逆に撮影した場合には左である可能性があります）。