カスタムキャプチャとレンダリング

最終更新日:2021-10-18 10:29:41

    内容紹介

    • ビデオキャプチャのカスタマイズ
      美顔や特殊効果処理モジュールを自社開発(またはサードパーティから購入)する場合は、カメラで撮影した画面を自身でキャプチャし処理する必要があります。この場合はTRTCCloudのenableCustomVideoCaptureインターフェースを介してTRTC SDK自体のカメラキャプチャと画像処理ロジックをオフにすることが可能です。その後 sendCustomVideoData インターフェースを使用し TRTC SDKに自身のビデオデータを入力することができます。
    • ビデオレンダリングのカスタマイズ
      TRTC SDKは、OpenGLを使用してビデオ画面のレンダリングを行います。ゲーム開発に使用する場合、または自身のインターフェースエンジンにTRTC SDKを埋め込む場合は、自身でビデオ画面をレンダリングする必要があります。
    • オーディオキャプチャのカスタマイズ
      特殊なハードウェアデバイスでTRTC SDKを使用し、外部の音声キャプチャデバイスに接続して自身で音声データをキャプチャする必要がある場合はTRTCCloudのenableCustomAudioCaptureインターフェースを介してTRTC SDKデフォルトのサウンドキャプチャプロセスをオフにする必要があります。その後、sendCustomAudioDataインターフェースを使用してTRTC SDKに自身の声音データを入力することができます。
      注意:

      オーディオキャプチャのカスタマイズを有効にすると、エコーキャンセル(AEC)機能が無効になる場合があります。

    • オーディオ生データの取得
      音声モジュールは非常に複雑で、SDKは音声デバイスのキャプチャおよび再生ロジックを厳密に制御する必要があります。一部シーンにおいて、リモートユーザーのオーディオデータまたはローカルマイクによってキャプチャされたオーディオデータを取得する必要がある場合は、TRTC SDKによって提供される対応するコールバックインターフェースを介して取得することができます。

    サポートするプラットフォーム

    iOS Android Mac OS Windows web Flutter
    ✓(Web ×

    ビデオキャプチャのカスタマイズ

    TRTCCloudのenableCustomVideoCaptureインターフェースを介してTRTC SDK自体のカメラキャプチャと画像処理ロジックをオフにします。その後、sendCustomVideoDataインターフェースを使用してTRTC SDKに自身のビデオデータを入力することができます。

    sendCustomVideoDataインターフェースにTRTCVideoFrameと呼ばれるビデオ画像のフレームを表すパラメータがあります。不要なパフォーマンスロスを回避するため、TRTC SDKに入力されるビデオデータには、プラットフォームごとに異なるフォーマット要件があります。具体的な要件は次のとおりです。

    TRTC SDKはNV12とi420という2種類のiOSバージョンのYUVデータ形式をサポートします。iOSプラットフォームにおいて、より高性能な画像転送方法はCVPixelBufferRefであるため、次のパラメータ形式を推奨します。

    パラメータ名パラメータタイプ推奨値付注
    pixelFormatTRTCVideoPixelFormatTRTCVideoPixelFormat_NV12iOSプラットフォーム上でカメラでキャプチャされるネイティブのビデオ形式はNV12です。
    bufferTypeTRTCVideoBufferTypePixelBufferiOSでネイティブにサポートされているビデオフレーム形式。最も高いパフォーマンスを発揮します。
    pixelBufferCVPixelBufferRefTRTCVideoBufferTypeがPixelBufferの場合は入力する必要があります。iPhoneのカメラでキャプチャされるデータはNV12形式のPixelBufferです。
    dataNSData*TRTCVideoBufferTypeがNSDataの場合は入力する必要があります。性能はPixelBufferほど高くありません。
    timestampuint64_t00を入力できます。SDKはこのようにtimestampフィールドへの入力をカスタマイズできますが、sendCustomVideoDataの呼び出し間隔を均等に制御してください。
    widthuint64_tビデオ画面の幅渡される画面のピクセル幅を正確に入力してください。
    heightuint32_tビデオ画面の高さ渡される画面のピクセル高さを正確に入力してください。
    rotationTRTCVideoRotation未入力
    • デフォルトは未入力。
    • 画面を回転させたい場合は、TRTCVideoRotation_0TRTCVideoRotation_90TRTCVideoRotation_180TRTCVideoRotation_270と入力します。SDKがその値に応じて対応する角度にビデオを時計回りに回転させます。例えば、縦画面の場合、TRTCVideoRotation_90と入力すると、SDKが画面を回転させて横表示にします。

    サンプルコード

    [Demo]フォルダの中にTestSendCustomVideoData.mという名のファイルがあり、これにはローカルビデオファイルの中からNV12形式のPixelBufferを読み取り、SDKを介して後続の処理を行う方法が示されています。

    //TRTCVideoFrameをアセンブルし、trtcCloudオブジェクトに送信します
    TRTCVideoFrame* videoFrame = [TRTCVideoFrame new];
    videoFrame.bufferType = TRTCVideoBufferType_PixelBuffer;
    videoFrame.pixelFormat = TRTCVideoPixelFormat_NV12;
    videoFrame.pixelBuffer = CMSampleBufferGetImageBuffer(sampleBuffer);
    
    

    [trtcCloud sendCustomVideoData:videoFrame];

    ビデオレンダリングのカスタマイズ

    TRTC SDKは、OpenGLを使用してビデオ画面のレンダリングを行います。ゲーム開発に使用する場合、または自身のインターフェースエンジンにTRTC SDKを埋め込む場合は、自身でビデオ画面をレンダリングする必要があります。

    TRTCCloudのsetLocalVideoRenderDelegatesetRemoteVideoRenderDelegateを介してローカルとリモート画面のカスタムレンダリングのコールバックを設定します。関連パラメータは次のとおりです。

    パラメータ名パラメータタイプ推奨値付注
    pixelFormatTRTCVideoPixelFormatTRTCVideoPixelFormat_NV12-
    bufferTypeTRTCVideoBufferTypeTRTCVideoBufferType_PixelBufferiOSでネイティブにサポートされているビデオフレーム形式。最も高いパフォーマンスを発揮します。

    サンプルコード

    pixelFormatがTRTCVideoPixelFormat_NV12を選択し、bufferTypeがTRTCVideoBufferType_PixelBufferを選択する場合は、NV12形式のPixelBufferをビデオイメージに簡単に変換することができます。DemoフォルダにTestRenderVideoFrame.m と呼ばれるファイルがあり、その中に次のサンプルコードを使用したこの方法の使用法が示されています。

    - (void)onRenderVideoFrame:(TRTCVideoFrame *)frame 
                                  userId:(NSString *)userId 
                            streamType:(TRTCVideoStreamType)streamType
    {
      //userIdがnilの場合はローカル画面、nilでない場合はリモート画面です
      CFRetain(frame.pixelBuffer);
      __weak __typeof(self) weakSelf = self;
      dispatch_async(dispatch_get_main_queue(), ^{
          TestRenderVideoFrame* strongSelf = weakSelf;
          UIImageView* videoView = nil;
          if (userId) {
              videoView = [strongSelf.userVideoViews objectForKey:userId];
          }
          else {
              videoView = strongSelf.localVideoView;
          }
          videoView.image = [UIImage imageWithCIImage:[CIImage imageWithCVImageBuffer:frame.pixelBuffer]];
          videoView.contentMode = UIViewContentModeScaleAspectFit;
          CFRelease(frame.pixelBuffer);
      });
    }
    

    オーディオキャプチャのカスタマイズ

    TRTCCloudのenableCustomAudioCaptureインターフェースを介してTRTC SDKデフォルトのサウンドキャプチャプロセスをオフにする必要があります。その後、sendCustomAudioDataインターフェースを使用してTRTC SDKに自身の声音データを入力することができます。

    sendCustomAudioDataインターフェースに1フレームが20msの長さのオーディオデータを表すTRTCAudioFrameと呼ばれるパラメータがあります。

    • sendCustomAudioData を介してSDKに送信されるデータは 、AACや他の圧縮形式ではなく、PCMフォーマットの非圧縮オーディオ生データでなければなりません。
    • sampleRateとchannelsはそれぞれサウンドサンプルレートとサウンドチャンネル数を意味します。渡されるPCMデータと厳密に一致させてください。
    • フレームごとのオーディオデータの推奨時間は20msであり、次のように計算することができます。sampleRateが48000、サウンドチャンネルが1(シングルサウンドチャンネル)である場合、sendCustomAudioDataの各呼び出しで渡されるbufferの長さは:48000 * 0.02s * 1 * 16bit = 15360bit = 1920バイトでなければなりません。
    • timestampは0にすることができます。timestampが0である場合、SDKはオーディオタイムスタンプを自動的に入力します。以上より、オーディオタイムスタンプの安定性を確保するため、sendCustomAudioData均等に呼び出し、20msに1度の頻度を確保してください。そうしなければ、声音が途切れるという結果を招くおそれがあります。
    注意:

    sendCustomAudioDataを使用すると、エコーキャンセル(AEC)の機能が無効になる場合があります。

    オーディオ生データの取得

    音声モジュールは非常に複雑で、SDKは音声デバイスのキャプチャおよび再生ロジックを厳密に制御する必要があります。一部シーンにおいて、リモートユーザーのオーディオデータまたはローカルマイクによってキャプチャされたオーディオデータを取得する必要がある場合は、TRTCCloudに対応する異なるプラットフォームのインターフェースを介して、3つのコールバック関数をSDKに統合できます。

    TRTCCloudの対応するプラットフォームごとのインターフェースはそれぞれ以下となります。
    • iOS:setAudioFrameDelegate。
    • Android:setAudioFrameListener。
    • Windows:setAudioFrameCallback。
    インターフェース 説明
    onCapturedAudioFrame ローカルマイクでキャプチャしたオーディオ生データを取得します。ユーザー定義キャプチャモードでないときは、SDKがマイクの音声のキャプチャを担当しますが、SDKがキャプチャしたオーディオ生データを取得したい場合には、このコールバック関数を介して取得することができます。
    onPlayAudioFrame この関数は各リモートユーザーのミキシング前の声音データをコールバックします。特定のチャネルの音声に対して音声認識を行いたい場合は、このコールバックを使用することができます。
    onMixedPlayAudioFrame 各チャネルのオーディオデータをミキシングした後、再生のためにスピーカーに送信される前に、この関数を介してコールバックされます。
    注意:

    • 上記のコールバック関数の中で何らかの時間のかかる操作を行わないでください。直接コピーし、別のスレッドで処理することを推奨しますが、そうしない場合、音声の途切れまたはエコーキャンセル(AEC)の無効化などの問題が生じる恐れがあります。
    • 上記のコールバック関数の中でコールバックされるデータは読み取りとコピーのみが許され、修正することはできません。修正すると様々な不確定な影響が生じる恐れがあります。