plaud-embedded-android-sdk-skill

Plaud Embedded Android SDK スキル

このスキルでは、Plaud Embedded Android SDK の実装方法に関するコンテキストと手順を説明します。

このスキルを使用する場面

ユーザーが、ネイティブ Android アプリを Plaud の録音デバイス（Plaud NotePin S および Plaud Note Pro）に接続したい場合に、このスキルを使用してください。

このスキルを使い始める前に、ユーザーが以下の前提条件を満たしていることを確認してください。

前提条件

• Plaud Developer Portal から Plaud Embedded の認証情報（CLIENT_ID、CLIENT_SECRET、API_KEY）を取得済みである
• Plaud の Authentication API を通じて User Token を取得する方法がある

ユーザーがこれらの前提条件を両方とも満たしていない場合は、手順について plaud-embedded-project-setup-skill を使用してください。

はじめに

インストールガイドの手順に従ってください。

Plaud Starter App のデプロイ方法

Plaud Starter App は、Embedded SDK がすでに実装された、完成済みの Android アプリです。

Starter App には、ユーザーがすぐに利用できる多数の機能が備わっています。

ユーザーに Starter App リポジトリをクローンして、Starter App ガイドの手順を進めるよう案内してください。Android スターターアプリは、plaud-sdk-public 内の android/ にあります。

認証情報は、android/ ディレクトリ内の Git 管理対象外の local.properties に設定します。PLAUD_USER_ACCESS_TOKEN は SDK の初期化に必須で、PLAUD_CLIENT_ID と PLAUD_API_KEY は Transcription API の利用時にのみ必要です。

Android 向け Embedded SDK の実装方法

Embedded SDK は、以下の機能を提供する Android ライブラリです。

1. Plaud デバイスをユーザーの Android モバイルアプリに接続（バインド）および接続解除する
2. BLE または WiFi Fast Transfer（約 10 倍高速）を使って、Plaud デバイスからユーザーのモバイルアプリに音声を同期する（すべての録音を一括ダウンロードする機能を含む）
3. 複数の形式（AudioExportFormat.PCM | WAV | OPUS | MP3）で音声を書き出す。MP3 を推奨します。どこでも再生でき、文字起こしアップロード API でそのまま使用できます。
4. 接続された Plaud デバイスのファームウェアを OTA で更新する

高レベルのファサードは、PlaudDeviceAgent（静的に呼び出す Kotlin の object で、インスタンスの生成は不要です）と IWifiTransferAgent（PlaudDeviceAgent.getWifiAgent() で取得します。戻り値は nullable なので、必ずセーフコールを使用してください）の 2 つです。initSDK(context:userAccessToken:customDomain:) で一度だけ初期化してください。customDomain には Plaud のドメインを指定しますが、https:// のプレフィックスは含めないでください（例：platform-us.plaud.ai）。

この SDK はコールバック駆動型のライブラリです。コールバック（PlaudDeviceAgentListener、AudioExporter.ExportCallback、IWifiTransferAgent.WifiTransferCallback、FirmwareUpdateCallback）を実装して、デバイスのイベント、転送の進捗状況、結果を受け取ります。

• PlaudDeviceAgentListener に必須メンバーは 0 個 です。グローバルリスナーを 1 つ PlaudDeviceAgent.listener に設定し、必要なものだけをオーバーライドしてください。
• IWifiTransferAgent.WifiTransferCallback には必須メンバーが 12 個 あります。デフォルト実装はありません。

BLE スキャンにはランタイム権限が必要です。SDK の sdk.permission.PermissionManager を使用してください。必要な権限一式（API 31 以降では BLUETOOTH_SCAN、BLUETOOTH_CONNECT、ACCESS_FINE_LOCATION、ACCESS_COARSE_LOCATION、API 30 以下では BLUETOOTH、BLUETOOTH_ADMIN、および両方の位置情報権限）を要求します。

重要（Android 固有）：connectBleDevice(...) を呼び出す前に、以下の 2 つを準備してください。準備されていない場合、セキュアハンドシェイクに失敗します。

1. パートナー RSA キーペアを取得済みである（initSDK によって取得されます。NiceBuildSdk.isPartnerDataReady() をポーリングしてください）
2. シリアル番号が署名され、NiceBuildSdk.signAndStoreDeviceSn(deviceType, sn) によって保存されている 重要：Plaud デバイスは一度に1 つのアプリケーションにしか紐付けられません。アプリをアンインストールする前に、必ずデバイスの紐付けを解除するようユーザーに伝えてください。解除しない場合、復旧するまで別のアプリ（Plaud アプリを含む）に紐付けられなくなります。

注記：デバイスの紐付けと解除を行う際は、API を呼び出す前に、まず SDK のメソッドを使用してください。これにより、クラウドの状態にデバイスの実際の状態が反映されます。デバイスの紐付けまたは解除に失敗した場合は、API を呼び出さないでください。

SDK に含まれる主要なメソッドとコールバックについては、Android SDK のドキュメントを参照してください。

高レベルのファサードで公開されていない動作については、低レベルの IBleAgent、NiceBuildSdk、PartnerApiManager を取り上げたAndroid SDK の高度な使用方法に関するドキュメントを参照してください。高レベルと低レベルのファサードは組み合わせて使用できますが、PlaudDeviceAgent を主な制御役として使用してください。これは、レスポンス管理、コールバックの接続、オーディオパイプライン（ダウンロード、キャッシュ、E2EE 復号、トランスコード）、ファームウェアのオーケストレーションを処理します。

詳しくは、以下を参照してください。

• ビルド済みの plaud-sdk.aar を含む SDK リポジトリ
• Android Embedded SDK が完全に実装された Plaud Starter App
• Starter App で参考にするのに最も関連性の高いファイル：
  • DeviceManager.kt
  • SyncManager.kt

完了の定義 - Embedded SDK の実装完了

ユーザーが以下を実行できること：

• Plaud デバイスをモバイルアプリに接続する
• BLE または WiFi 高速転送を使用して、Plaud デバイスからアプリにオーディオファイルを同期する
• アプリから Plaud デバイスの紐付けを解除する（クラウドと BLE の両方で）