サードパーティ連携

SDK 2.0.0。Facebetter をサードパーティ SDK のカスタム動画前処理コールバックに接続します。相手が提供する OpenGL スレッド（またはピクセルバッファコールバック）上でフレームを処理し、相手へ返します。 iOS · サードパーティ連携と同じ Objective-C API を共有します。差は主にランタイム環境（OpenGL、App Sandbox、プロセス名バインド）です。テクスチャの完全な契約: 美顔の実装 · 外部テクスチャ。

Third-party SDK
  textureId or CVPixelBuffer
       ↓
FBBeautyEffectEngine
  createWithTexture / createWithNV12|BGRA → processImage:
       ↓
  output texture or pixels → write back to vendor frame

共通の契約

項目	要件
テクスチャ経路	`externalContext = YES`。相手の GL コールバックスレッドで遅延 `createEngineWithConfig:`
入力テクスチャ	`GL_TEXTURE_2D`（RGBA）。`stride` は通常 `width * 4`
ピクセルバッファ経路	`createWithNV12:` / `createWithBGRA:` などを使用。この場合は通常 `externalContext = NO` で、Facebetter が GL を管理
フレームタイプ	`FBFrameTypeVideo`
出力	出力テクスチャは SDK が所有。`glDeleteTextures` しない。エンジンは strong 参照。セッション終了時は `nil`
サンドボックス	オンライン認証には Outgoing Connections が必要。オフラインは `licenseToken` / `.lic`

Apple プラットフォームでは、TRTC カスタム前処理は OpenGL テクスチャが一般的です。Agora / LiveKit は CVPixelBuffer がより一般的です。どちらも使えますが、同じエンジンで 2 つのモードを混在させないでください。

共通: テクスチャ処理

#import <Facebetter/Facebetter.h>

static GLuint FBProcessTexture(FBBeautyEffectEngine *engine,
                               GLuint srcTextureId,
                               int width,
                               int height) {
  if (!engine || srcTextureId == 0 || width <= 0 || height <= 0) {
    return srcTextureId;
  }
  FBImageFrame *input = [FBImageFrame createWithTexture:srcTextureId
                                                  width:width
                                                 height:height
                                                 stride:width * 4];
  if (!input) {
    return srcTextureId;
  }
  input.type = FBFrameTypeVideo;
  FBImageFrame *output = [engine processImage:input];
  if (!output) {
    return srcTextureId;
  }
  GLuint dst = [output texture];
  return dst != 0 ? dst : srcTextureId;
}

エンジン作成（GL スレッド）:

FBEngineConfig *config = [[FBEngineConfig alloc] init];
config.appId = @"your appId";
config.appKey = @"your appKey";
// or config.licenseToken = @"...";
config.externalContext = YES;
self.beautyEngine = [FBBeautyEffectEngine createEngineWithConfig:config];
[self.beautyEngine setSmoothing:0.5f];

共通: CVPixelBuffer の処理（NV12 の例）

Agora / LiveKit コールバックでは NV12 が一般的です。プレーンポインタと stride は CVPixelBuffer から取得します。相手フレームへの書き戻しはベンダーバージョンで変わります。

static FBImageFrame *FBFrameFromNV12PixelBuffer(CVPixelBufferRef pb) {
  OSType fmt = pb ? CVPixelBufferGetPixelFormatType(pb) : 0;
  if (!pb || (fmt != kCVPixelFormatType_420YpCbCr8BiPlanarFullRange
              && fmt != kCVPixelFormatType_420YpCbCr8BiPlanarVideoRange)) {
    return nil;
  }
  CVPixelBufferLockBaseAddress(pb, kCVPixelBufferLock_ReadOnly);
  int width = (int)CVPixelBufferGetWidth(pb);
  int height = (int)CVPixelBufferGetHeight(pb);
  uint8_t *y = (uint8_t *)CVPixelBufferGetBaseAddressOfPlane(pb, 0);
  uint8_t *uv = (uint8_t *)CVPixelBufferGetBaseAddressOfPlane(pb, 1);
  int strideY = (int)CVPixelBufferGetBytesPerRowOfPlane(pb, 0);
  int strideUV = (int)CVPixelBufferGetBytesPerRowOfPlane(pb, 1);
  FBImageFrame *frame = [FBImageFrame createWithNV12:width
                                              height:height
                                               dataY:y
                                             strideY:strideY
                                              dataUV:uv
                                            strideUV:strideUV];
  CVPixelBufferUnlockBaseAddress(pb, kCVPixelBufferLock_ReadOnly);
  return frame;
}

ピクセルバッファ経路では、エンジン作成時に externalContext = NO を設定します。認証情報: サブスクリプション、認証とライセンス。

TRTC（Tencent Cloud）

フック API: setLocalVideoProcessDelegete:pixelFormat:bufferType:（公式の綴りは Delegete）。ピクセルフォーマット TRTCVideoPixelFormat_Texture_2D、バッファタイプ TRTCVideoBufferType_Texture。 TRTCVideoFrameDelegate を実装します。onGLContextCreated でエンジンを作成し、onProcessVideoFrame:dstFrame: で dstFrame.textureId を書き戻し、onGLContextDestory でエンジンを nil にします。

#import <TXLiteAVSDK_TRTC/TRTCCloud.h>
#import <Facebetter/Facebetter.h>

@interface BeautyProcessDelegate : NSObject <TRTCVideoFrameDelegate>
@property (nonatomic, strong) FBBeautyEffectEngine *beautyEngine;
@end

@implementation BeautyProcessDelegate

- (void)onGLContextCreated {
  FBEngineConfig *config = [[FBEngineConfig alloc] init];
  config.appId = @"your appId";
  config.appKey = @"your appKey";
  config.externalContext = YES;
  self.beautyEngine = [FBBeautyEffectEngine createEngineWithConfig:config];
  [self.beautyEngine setSmoothing:0.5f];
}

- (uint32_t)onProcessVideoFrame:(TRTCVideoFrame *)srcFrame
                       dstFrame:(TRTCVideoFrame *)dstFrame {
  GLuint out = FBProcessTexture(self.beautyEngine,
                                srcFrame.textureId,
                                srcFrame.width,
                                srcFrame.height);
  dstFrame.textureId = out;
  return 0;
}

- (void)onGLContextDestory {
  self.beautyEngine = nil;
}

@end

// register
BeautyProcessDelegate *delegate = [[BeautyProcessDelegate alloc] init];
[[TRTCCloud sharedInstance] setLocalVideoProcessDelegete:delegate
                                             pixelFormat:TRTCVideoPixelFormat_Texture_2D
                                              bufferType:TRTCVideoBufferType_Texture];

デリゲート解除または退室後にエンジンを解放します。詳細は Tencent Cloud の TRTC サードパーティ美顔。 Flutter では Flutter · サードパーティ連携（FacebetterPlugin.processTexture）を使います。

Agora

フック API: AgoraRtcEngineKit.setVideoFrameDelegate:（Video SDK 4.x）。macOS のキャプチャフレームも多くが CVPixelBuffer です。必要なこと:

getVideoFrameProcessMode が ReadWrite を返す
onCapture:sourceType:（または旧名 onCaptureVideoFrame）で CVPixelBuffer を取り出す
createWithNV12: / createWithBGRA: などで Facebetter に渡し、結果を AgoraOutputVideoFrame に書き戻す

#import <AgoraRtcKit/AgoraRtcKit.h>

@interface BeautyFrameDelegate : NSObject <AgoraVideoFrameDelegate>
@property (nonatomic, strong) FBBeautyEffectEngine *beautyEngine;
@end

@implementation BeautyFrameDelegate

- (AgoraVideoFrameProcessMode)getVideoFrameProcessMode {
  return AgoraVideoFrameProcessModeReadWrite;
}

- (BOOL)onCapture:(AgoraOutputVideoFrame *)videoFrame
       sourceType:(AgoraVideoSourceType)sourceType {
  CVPixelBufferRef pb = videoFrame.pixelBuffer; // some versions use textureBuf; follow your headers
  if (!pb) {
    return YES;
  }

  if (!self.beautyEngine) {
    FBEngineConfig *config = [[FBEngineConfig alloc] init];
    config.appId = @"your appId";
    config.appKey = @"your appKey";
    config.externalContext = NO; // pixel-buffer path
    self.beautyEngine = [FBBeautyEffectEngine createEngineWithConfig:config];
  }

  FBImageFrame *input = FBFrameFromNV12PixelBuffer(pb);
  if (!input) {
    return YES; // not NV12: use BGRA factory or convert first
  }
  input.type = FBFrameTypeVideo;
  FBImageFrame *output = [self.beautyEngine processImage:input];
  if (!output) {
    return YES;
  }

  // Write output NV12/BGRA planes back into videoFrame's CVPixelBuffer,
  // or replace pixelBuffer / textureBuf per Agora docs. Details vary by SDK version.
  return YES;
}

@end

[agoraKit setVideoFrameDelegate:delegate];

Agora macOS 側で CVPixelBuffer を書き戻す方法はメジャーバージョンで変わります。Facebetter は processImage: の出力が入力と同じフォーマットであることを保証します。AgoraOutputVideoFrame への差し込みは Agora の生動画処理に従ってください。

エンジン破棄前に setVideoFrameDelegate:nil し、beautyEngine を nil にします。

LiveKit

フック: Swift VideoProcessor を実装し、process(frame:) で処理して新しいフレームを返します（または nil でドロップ）。カメラトラック作成時に processor: を渡すか、あとから track.processor を設定します。

import LiveKit
import Facebetter // per your module name

final class FacebetterVideoProcessor: VideoProcessor {
  private var beautyEngine: FBBeautyEffectEngine?

  func process(frame: VideoFrame) -> VideoFrame? {
    // Take CVPixelBuffer from LiveKit VideoFrame (property name may be
    // buffer / pixelBuffer / rtcFrame per SDK version; check LiveKit Swift headers)
    guard let pb = frame.buffer as CVPixelBuffer? else {
      return frame
    }

    if beautyEngine == nil {
      let config = FBEngineConfig()
      config.appId = "your appId"
      config.appKey = "your appKey"
      config.externalContext = false
      beautyEngine = FBBeautyEffectEngine.createEngine(with: config)
      beautyEngine?.setSmoothing(0.5)
    }

    // ObjC helper: FBFrameFromNV12PixelBuffer → processImage:
    // then wrap output as a LiveKit VideoFrame and return
    // wrapping steps: LiveKit "Video Processors" docs
    return frame
  }
}

let processor = FacebetterVideoProcessor()
let track = LocalVideoTrack.createCameraTrack(processor: processor)
// or: track.processor = processor
try await room.localParticipant.publish(track: track)

公式サンプルプロセッサ（背景ぼかしなど）は LiveKit Swift の BackgroundBlurVideoProcessor（macOS 12+）を参照してください。画面共有トラックにも同じ processor を付けられます（API は現在の LiveKit Swift に従ってください）。

トラブルシューティング

症状	確認
黒画面 / 映像なし	テクスチャ経路が相手の GL スレッドでエンジンを作成しているか。ピクセル経路で `CVPixelBuffer` の lock/unlock をしているか
美顔が効かない	`externalContext` が経路と一致しているか（テクスチャ YES / ピクセルは多く NO）。フォーマットが NV12/BGRA/`GL_TEXTURE_2D` か
断続的なクラッシュ	`onGLContextDestory` で `nil` にしたか。出力テクスチャを誤削除していないか
歪み / 引き伸ばし	幅高さ、回転、ミラーが相手フレームと一致しているか。stride に `BytesPerRow` を使っているか

はじめに

Android

iOS

macOS

Windows

Linux

Web

Flutter

サードパーティ連携

共通の契約

共通: テクスチャ処理

共通: CVPixelBuffer の処理（NV12 の例）

TRTC（Tencent Cloud）

Agora

LiveKit

トラブルシューティング

関連ドキュメント

​共通の契約

​共通: テクスチャ処理

​共通: CVPixelBuffer の処理（NV12 の例）

​TRTC（Tencent Cloud）

​Agora

​LiveKit

​トラブルシューティング

​関連ドキュメント

共通の契約

共通: テクスチャ処理

共通: CVPixelBuffer の処理（NV12 の例）

TRTC（Tencent Cloud）

Agora

LiveKit

トラブルシューティング

関連ドキュメント