Plaud Developer Platform

https://docs.plaud.ai/
Admin
Plaud Developer Platform enables developers to embed AI-powered notetaking and conversational...
Tokens:51,798
Snippets:531
Trust Score:10
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install dependencies and configure environment

Source: https://docs.plaud.ai/plaud-embedded/web-app-wrapper

Navigate to the demo directory, install required packages, and initialize the environment variables.

```bash
cd nextjs-demo
npm i
cp .env.example .env
```

--------------------------------

### Plaud CLI Quick Start Commands

Source: https://docs.plaud.ai/plaud-mcp-cli/cli

Basic commands to get started with Plaud CLI, including login, browsing files, searching, and retrieving summaries or transcripts.

```bash
plaud login          # sign in via browser
plaud files          # browse your recordings
plaud search "Q2"    # find a recording by keyword
plaud summary <id>   # read the AI summary
plaud transcript <id> # read the full transcript
```

--------------------------------

### Install Android Studio via Homebrew

Source: https://docs.plaud.ai/plaud-embedded/android-starter-app

Install the required development environment using Homebrew.

```bash
brew install --cask android-studio
```

--------------------------------

### Install Capacitor Dependencies

Source: https://docs.plaud.ai/plaud-embedded/web-app-wrapper

Install the required Capacitor core and platform-specific packages.

```bash
npm i @capacitor/core @capacitor/ios @capacitor-community/bluetooth-le @capacitor/android
npm i -D @capacitor/cli
```

--------------------------------

### Install dependencies and configure environment

Source: https://docs.plaud.ai/plaud-embedded/flutter

Navigate to the project directory, fetch dependencies, and prepare the environment configuration file.

```bash
cd embedded-flutter
flutter pub get
cp .env.example .env
```

--------------------------------

### Reset Claude Desktop Setup

Source: https://docs.plaud.ai/plaud-mcp-cli/mcp

Re-runs the setup process to resolve server disconnection issues.

```bash
plaud-mcp unsetup && plaud-mcp setup
```

--------------------------------

### PlaudDeviceAgent.installFirmware

Source: https://docs.plaud.ai/plaud-embedded/android-sdk

Installs the downloaded firmware file onto the device.

```APIDOC
## PlaudDeviceAgent.installFirmware

### Description
Initiates the installation of the downloaded firmware file. The device will restart and reconnect upon completion.

### Parameters
- **file** (File) - Required - The firmware file obtained from the download process.
- **info** (FirmwareUpdateInfo) - Required - The update information returned by checkFirmwareUpdate.
- **callback** (FirmwareUpdateCallback) - Required - Reports installation progress and completion status.
```

--------------------------------

### Install Firmware Update in Kotlin

Source: https://docs.plaud.ai/plaud-embedded/android-sdk

Installs the downloaded firmware file to the device, triggering a restart and reconnection upon completion.

```kotlin
PlaudDeviceAgent.installFirmware(file, updateInfo, object : SimpleFirmwareUpdateCallback() {
    override fun onInstallProgress(progress: UpdateProgress) { }
    override fun onInstallComplete(result: FirmwareInstallResult) {
        if (result.success) {
            // device restarts and reconnects
        }
    }
})
```

--------------------------------

### Install Plaud CLI

Source: https://docs.plaud.ai/plaud-mcp-cli/changelog

Installs the Plaud CLI globally for terminal access to recordings and summaries.

```bash
npm install -g @plaud-ai/cli
```

--------------------------------

### PlaudDeviceAgent.startFirmwareUpdate

Source: https://docs.plaud.ai/plaud-embedded/ios-sdk

Performs the complete firmware update flow including download, installation, and device restart.

```APIDOC
## PlaudDeviceAgent.startFirmwareUpdate

### Description
Executes the full OTA update process in one call.

### Parameters
- **progress** ((PlaudFirmwarePhase, Float) -> Void) - Required - Callback reporting update progress.
- **completion** ((PlaudFirmwareUpdateResult) -> Void) - Required - Callback when the update completes.

### PlaudFirmwarePhase
- `downloading`: Firmware binary is being downloaded
- `installing`: Firmware is being installed on the device
- `restarting`: Device is restarting after installation
- `complete`: Update finished successfully

### PlaudFirmwareUpdateResult
- **success** (Bool) - Whether the update succeeded
- **version** (String) - The firmware version after update
- **errorMessage** (String) - Error description if update failed
```

--------------------------------

### Run Firmware Update in Swift

Source: https://docs.plaud.ai/plaud-embedded/ios-sdk

Executes the complete OTA flow including download, installation, and restart, with progress tracking.

```swift
// One-call firmware update
PlaudDeviceAgent.shared.startFirmwareUpdate(
    progress: { phase, percentage in
        // phase: .downloading / .installing / .restarting / .complete
        // percentage: 0.0 ~ 1.0
    },
    completion: { result in
        if result.success {
            print("Updated to \(result.version)")
        } else {
            print("Failed: \(result.errorMessage ?? "")")
        }
    }
)
```

--------------------------------

### Install Plaud MCP

Source: https://docs.plaud.ai/plaud-mcp-cli/changelog

Installs the Plaud MCP package for use with MCP-compatible AI clients.

```bash
npx -y @plaud-ai/mcp@latest install
```

--------------------------------

### Start WiFi Transfer Session

Source: https://docs.plaud.ai/plaud-embedded/android-sdk

Starts the transfer session within the bleWiFiOpen callback. The SDK manages the hotspot connection and secure handshake.

```kotlin
PlaudDeviceAgent.listener = object : PlaudDeviceAgentListener {
    override fun bleWiFiOpen(status: Int, ssid: String, password: String, url: String) {
        PlaudDeviceAgent.startWifiTransfer(userId, wifiCallback)
    }
    // ...
}
```

--------------------------------

### POST /developer/api/open/partner/users/access-token

Source: https://docs.plaud.ai/plaud-embedded/api-playground

Get a user-level token.

```APIDOC
## POST /developer/api/open/partner/users/access-token

### Description
Issues a user-level token to bind devices and upload files.

### Method
POST

### Endpoint
https://platform-us.plaud.ai/developer/api/open/partner/users/access-token

### Request Body
- **user_id** (string) - Required - The ID of the user.
- **expires_in** (integer) - Required - Token expiration time in seconds.
```

--------------------------------

### Generate Presigned URLs Request Example

Source: https://docs.plaud.ai/api-reference/file-upload-api/generate-presigned-upload-urls

The request body requires the total file size in bytes and the file extension.

```json
{
  "filesize": 10485760,
  "filetype": "mp3"
}
```

--------------------------------

### Complete Multipart Upload Response Example

Source: https://docs.plaud.ai/api-reference/file-upload-api/complete-multipart-upload

Successful response containing the file identifier and a pre-signed download URL for the merged file.

```json
{
  "FileId": "file_xxx",
  "FileType": "mp3",
  "DownloadUrl": "https://plaud-bucket.s3.amazonaws.com/...",
  "FileMd5": "9e107d9d372bb6826bd81d3542a419d6"
}
```

--------------------------------

### POST /developer/api/oauth/partner/access-token

Source: https://docs.plaud.ai/plaud-embedded/api-playground

Get a partner token for authentication.

```APIDOC
## POST /developer/api/oauth/partner/access-token

### Description
Retrieves a partner access token using Basic authentication.

### Method
POST

### Endpoint
https://platform-us.plaud.ai/developer/api/oauth/partner/access-token
```

--------------------------------

### Upgrade Plaud AI CLI to Latest Version

Source: https://docs.plaud.ai/plaud-mcp-cli/cli

Install the latest version of the Plaud AI CLI globally using npm.

```bash
npm install -g @plaud-ai/cli@latest
```

--------------------------------

### GET /open/partner/ai/transcriptions/{transcription_id}

Source: https://docs.plaud.ai/api-reference/transcription-api/get-transcription-task

Retrieve the status and results of a transcription task. Keep polling while the status is PENDING, RECEIVED, STARTED, or PROGRESS. When the status is SUCCESS, the data object is populated.

```APIDOC
## GET /open/partner/ai/transcriptions/{transcription_id}

### Description
Retrieve the status and results of a transcription task. Keep polling while the status is `PENDING`, `RECEIVED`, `STARTED`, or `PROGRESS`. When the status is `SUCCESS`, the `data` object is populated.

### Method
GET

### Endpoint
/open/partner/ai/transcriptions/{transcription_id}

### Parameters
#### Path Parameters
- **transcription_id** (string) - Required - The `transcription_id` returned when the audio was submitted.

### Response
#### Success Response (200)
- **transcription_id** (string) - The ID of the transcription task.
- **status** (string) - The current status of the task (`PENDING`, `RECEIVED`, `STARTED`, `PROGRESS`, `SUCCESS`, `FAILURE`, `REVOKED`).
- **data** (object) - Populated when the status is `SUCCESS`. Contains `text`, `language`, `duration`, and `results`.

#### Response Example
{
  "transcription_id": "task_exec_xxx",
  "status": "SUCCESS",
  "data": {
    "text": "Meeting started at 10am...",
    "language": "en",
    "duration": 1843,
    "results": [
      {
        "start": 0,
        "end": 4.2,
        "text": "Meeting started at 10am.",
        "speaker_id": "Speaker 1",
        "language": "en-US",
        "language_probability": "0.941"
      }
    ]
  }
}
```

--------------------------------

### Build the demo app for Android

Source: https://docs.plaud.ai/plaud-embedded/react-native

Generate the native Android project and launch the application on a connected device.

```bash
npx expo prebuild -p android
npx expo run:android
```

--------------------------------

### Clone the Starter App Repository

Source: https://docs.plaud.ai/plaud-embedded/android-starter-app

Download the starter app source code and navigate to the Android directory.

```bash
git clone https://github.com/Plaud-AI/plaud-sdk-public.git
cd plaud-sdk-public/android
```

--------------------------------

### Build the demo app for mobile platforms

Source: https://docs.plaud.ai/plaud-embedded/web-app-wrapper

Synchronize Capacitor assets and open the project in the respective native IDEs for iOS and Android.

```bash
# for ios
npx cap sync ios
npx cap open ios

# for android
npx cap sync android
npx cap open android
```

--------------------------------

### Run the demo app on a physical device

Source: https://docs.plaud.ai/plaud-embedded/flutter

Execute the application using the required environment variables defined in the .env file.

```bash
flutter run --dart-define-from-file=.env
```

--------------------------------

### Install Plugin in Claude Code

Source: https://docs.plaud.ai/plaud-mcp-cli/mcp

Command to be executed inside the Claude Code interface to install the Plaud plugin.

```text
/plugin install plaud
```

--------------------------------

### Build the demo app for iOS

Source: https://docs.plaud.ai/plaud-embedded/react-native

Generate the native iOS project and open the workspace in Xcode for final configuration.

```bash
npx expo prebuild -p ios
open ios/reactnativedemo.xcworkspace
```

--------------------------------

### Initialize Capacitor

Source: https://docs.plaud.ai/plaud-embedded/web-app-wrapper

Initialize the Capacitor configuration in your project.

```bash
npx cap init
```

--------------------------------

### Plaud CLI Error Output Example

Source: https://docs.plaud.ai/plaud-mcp-cli/cli

Example of an error message written to stderr by the Plaud CLI, indicating an authentication failure.

```bash
✖ [AUTH_FAILED] Token invalid or expired. Run `plaud login`.
```

--------------------------------

### initSDK(userAccessToken:customDomain:)

Source: https://docs.plaud.ai/plaud-embedded/ios-sdk

Initializes the Plaud Device SDK with the required user authentication token and regional server domain.

```APIDOC
## initSDK(userAccessToken:customDomain:)

### Description
Initializes the Plaud Device SDK. This must be called to configure the SDK with the user's access token and the regional domain for network requests.

### Parameters
- **userAccessToken** (string) - Required - User Access Token (JWT), used for device authentication.
- **customDomain** (string) - Required - Your regional Plaud server domain without the https:// prefix.
```

--------------------------------

### OpenAPI Specification for Get Transcription Task

Source: https://docs.plaud.ai/api-reference/transcription-api/get-transcription-task

Defines the GET endpoint for retrieving transcription task status and results, including security schemes and response schemas.

```yaml
openapi: 3.0.4
info:
  title: Transcription API
  description: >-
    Submit audio for transcription and poll for results. Authenticate with the
    API key headers (`client_id` / `api_key`) issued alongside `secret_key` in
    the Portal.
  version: 0.0.1
servers:
  - url: https://platform-us.plaud.ai/developer/api
    description: US partner endpoint
  - url: https://platform-jp.plaud.ai/developer/api
    description: Japan partner endpoint
security: []
paths:
  /open/partner/ai/transcriptions/{transcription_id}:
    get:
      tags:
        - Transcription API
      summary: Get Transcription Task
      description: >-
        Retrieve the status and results of a transcription task. Keep polling
        while the status is `PENDING`, `RECEIVED`, `STARTED`, or `PROGRESS`.
        When the status is `SUCCESS`, the `data` object is populated.
      operationId: getTranscription
      parameters:
        - in: path
          name: transcription_id
          required: true
          schema:
            type: string
          description: The `transcription_id` returned when the audio was submitted.
          example: task_exec_xxx
      responses:
        '200':
          description: Transcription status and results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TranscriptionResultResponse'
              example:
                transcription_id: task_exec_xxx
                status: SUCCESS
                data:
                  text: Meeting started at 10am...
                  language: en
                  duration: 1843
                  results:
                    - start: 0
                      end: 4.2
                      text: Meeting started at 10am.
                      speaker_id: Speaker 1
                      language: en-US
                      language_probability: '0.941'
      security:
        - clientId: []
          clientApiKey: []
components:
  schemas:
    TranscriptionResultResponse:
      type: object
      properties:
        transcription_id:
          type: string
          example: task_exec_xxx
        status:
          $ref: '#/components/schemas/TranscriptionStatus'
        data:
          type: object
          description: Populated when the status is `SUCCESS`.
          properties:
            text:
              type: string
              description: Full transcript text.
            language:
              type: string
              description: Detected or specified language.
            duration:
              type: integer
              description: Audio duration in seconds.
            results:
              type: array
              description: Time-aligned transcript segments.
              items:
                $ref: '#/components/schemas/TranscriptionSegment'
    TranscriptionStatus:
      type: string
      description: >-
        `PENDING`, `RECEIVED`, `STARTED`, `PROGRESS` indicate the task is in
        progress — keep polling. `SUCCESS` means the data is ready. `FAILURE`
        and `REVOKED` are terminal failures.
      enum:
        - PENDING
        - RECEIVED
        - STARTED
        - PROGRESS
        - SUCCESS
        - FAILURE
        - REVOKED
      example: PENDING
    TranscriptionSegment:
      type: object
      properties:
        start:
          type: number
          description: Segment start time, in seconds.
          example: 0
        end:
          type: number
          description: Segment end time, in seconds.
          example: 4.2
        text:
          type: string
          description: Transcript text for the segment.
          example: Meeting started at 10am.
        speaker_id:
          type: string
          description: Speaker label, present when diarization is enabled.
          example: Speaker 1
        language:
          type: string
          description: Language
          example: en-US
        language_probabilitiy:
          type: number
          description: Probability (0-1) of language confidence
          example: '0.94'
  securitySchemes:
    clientId:
      type: apiKey
      in: header
      name: X-Client-Id
      description: Your `client_id`, issued in the Portal.
    clientApiKey:
      type: apiKey
      in: header
      name: X-Client-Api-Key
      description: >-
        Your `api_key`, issued alongside `client_id` / `secret_key` in the
        Portal.
```

--------------------------------

### Run Flutter Application

Source: https://docs.plaud.ai/plaud-embedded/flutter

Fetch dependencies and run the application with environment configuration.

```bash
flutter pub get
flutter run --dart-define-from-file=.env
```

--------------------------------

### Wait for Ready State and List Files

Source: https://docs.plaud.ai/plaud-embedded/android-sdk

Monitors the connection state and requests the file list once the state reaches READY. File commands will fail if executed before this state.

```kotlin
val wifiCallback = object : IWifiTransferAgent.WifiTransferCallback {
    override fun onConnectionStateChanged(state: WifiConnectionState) {
        if (state == WifiConnectionState.READY) {
            PlaudDeviceAgent.getWifiAgent()?.getFileList()
        }
    }
    override fun onFileListReceived(files: List<WifiFileInfo>) {
        // export each session (next step)
    }
    override fun onError(code: Int, message: String) { }
    // ...
}
```

--------------------------------

### GET /developer/api/open/partner/ai/transcriptions/

Source: https://docs.plaud.ai/plaud-embedded/api-playground

Retrieve transcription task status.

```APIDOC
## GET /developer/api/open/partner/ai/transcriptions/

### Description
Retrieves the status or details of a transcription task.

### Method
GET

### Endpoint
https://platform-us.plaud.ai/developer/api/open/partner/ai/transcriptions/
```

--------------------------------

### Open Xcode Project

Source: https://docs.plaud.ai/plaud-embedded/ios-starter-app

Command to open the project file in Xcode for development and testing.

```bash
open PlaudTemplateApp.xcodeproj  # then ⌘R in Xcode
```

--------------------------------

### Get Transcription Task

Source: https://docs.plaud.ai/plaud-embedded/api-playground

Retrieves the status and results of a transcription task.

```curl
curl --request GET 
  --url https://platform-us.plaud.ai/developer/api/open/partner/ai/transcriptions/ 
  --header 'X-Client-Api-Key: ' 
  --header 'X-Client-Id: '
```

```json
{}
```

--------------------------------

### Initialize SDK

Source: https://docs.plaud.ai/plaud-embedded/android-sdk

Standalone initialization snippet for the PlaudDeviceAgent.

```kotlin
import sdk.PlaudDeviceAgent

PlaudDeviceAgent.initSDK(
    context = applicationContext,
    userAccessToken = "user-token",
    customDomain = "platform-us.plaud.ai"  // domain only, no https://
)
```

--------------------------------

### Upgrade Plaud MCP CLI

Source: https://docs.plaud.ai/plaud-mcp-cli/mcp

Updates the global installation of the Plaud MCP package.

```bash
npm install -g @plaud-ai/mcp@latest
```

--------------------------------

### Initialize Plaud SDK Agents

Source: https://docs.plaud.ai/plaud-embedded/ios-sdk

Initialize the device and Wi-Fi agents using the shared singleton and provide the required user token and regional domain.

```swift
import PlaudDeviceBasicSDK

let deviceAgent = PlaudDeviceAgent.shared
let wifiAgent = PlaudWiFiAgent.shared

// Initialize once with your user token and regional domain
deviceAgent.initSDK(
    userAccessToken: "user-token",
    customDomain: "platform-us.plaud.ai"  // domain only, no https://
)

// Assign delegates to receive device and transfer events
deviceAgent.delegate = self
wifiAgent.delegate = self
```

--------------------------------

### Get Partner Token

Source: https://docs.plaud.ai/plaud-embedded/api-playground

Authenticates the partner application using Basic Auth credentials.

```curl
curl --request POST
  --url https://platform-us.plaud.ai/developer/api/oauth/partner/access-token
  --header 'Authorization: Basic base64(:)'
  --header 'Content-Type: application/x-www-form-urlencoded'
```

```json
{}
```

--------------------------------

### Configure Partner Credentials

Source: https://docs.plaud.ai/plaud-embedded/ios-starter-app

Set the required access token and API credentials in the xcconfig file.

```bash
# Required for SDK initialization
USER_ACCESS_TOKEN = your-user-access-token

# Required for the Transcription API
PLAUD_CLIENT_ID = your-client-id
PLAUD_API_KEY   = your-api-key
```

--------------------------------

### Plaud CLI Utility Commands

Source: https://docs.plaud.ai/plaud-mcp-cli/cli

Check the installed Plaud CLI version and update status.

```bash
plaud version    # show installed version and build info
plaud update     # check for a newer version and print the upgrade command
```

--------------------------------

### Get User Token

Source: https://docs.plaud.ai/plaud-embedded/api-playground

Retrieves a user-level access token for device binding and file operations.

```curl
curl --request POST
  --url https://platform-us.plaud.ai/developer/api/open/partner/users/access-token
  --header 'Authorization: Bearer '
  --header 'Content-Type: application/json'
  --data '
  {
    "user_id": "",
    "expires_in": 86400
  }'
```

```json
{}
```

--------------------------------

### Copy SDK frameworks to project

Source: https://docs.plaud.ai/plaud-embedded/ios-sdk

Command to move the downloaded framework files into your local iOS application directory.

```bash
cp -R sdk/ios your/ios-app/library
```

--------------------------------

### Manage BLE permissions

Source: https://docs.plaud.ai/plaud-embedded/android-sdk

Use PermissionManager to request necessary Bluetooth and location permissions before starting a scan.

```kotlin
import sdk.permission.PermissionManager

class ScanActivity : AppCompatActivity() {
    private val perms by lazy { PermissionManager(this) }
    private fun startScanning() {
        if (perms.hasAllPermissions()) {
            PlaudDeviceAgent.startScan()
        } else {
            perms.requestPermissions(this) { granted -> onPermissionResult(granted) }
        }
    }

    override fun onRequestPermissionsResult(
        requestCode: Int,
        permissions: Array<out String>,
        grantResults: IntArray
    ) {
        super.onRequestPermissionsResult(requestCode, permissions, grantResults)
        perms.onRequestPermissionsResult(
            requestCode,
            arrayOf(*permissions),
            grantResults
        ) { granted -> onPermissionResult(granted) }
    }

    private fun onPermissionResult(granted: Boolean) {
        if (granted) PlaudDeviceAgent.startScan() else { /* ... */ }
    }
}
```

--------------------------------

### Initialize and Use Plaud SDK

Source: https://docs.plaud.ai/plaud-embedded/react-native

Import the PlaudSdk interface to initialize the SDK, manage listeners, and interact with devices.

```typescript
import { PlaudSdk } from 'plaud-sdk';

await PlaudSdk.initSDK({
  userAccessToken,
  customDomain: 'platform-us.plaud.ai',
  userId: 'your-app-user-id',
});

const subs = [
  PlaudSdk.addListener('scanResult', ({ devices }) => {/* show devices */}),
  PlaudSdk.addListener('connectState', ({ connected, failed }) => {
    if (connected) PlaudSdk.getFileList();      // ask for recordings once connected
  }),
  PlaudSdk.addListener('fileList', ({ files }) => {/* show recordings */}),
  PlaudSdk.addListener('exportProgress', ({ progress, message }) => {/* progress UI */}),
];

await PlaudSdk.startScan();
await PlaudSdk.connectBleDevice({ uuid: device.uuid });
const { outputPath } = await PlaudSdk.exportAudio({ sessionId, format: 'mp3' });

subs.forEach((s) => s.remove());
```

--------------------------------

### Connect to Plaud Device

Source: https://docs.plaud.ai/plaud-embedded/web-app-wrapper

Example of using the Plaud SDK to stop scanning and initiate a BLE connection to a device.

```typescript
import { Capacitor, type PluginListenerHandle } from "@capacitor/core";
import {
  PlaudSdk,
  readExportedFile,
  type PlaudScanDevice,
  type PlaudFile,
} from "@/lib/plaud-sdk";

const handleConnect = async (d: PlaudScanDevice) => {
    setError(null);
    if (!ensureNative()) return;
    try {
      setStatus(`connecting to ${d.name || d.serialNumber}…`);
      await PlaudSdk.stopScan();
      setScanning(false);
      await PlaudSdk.connectBleDevice({ uuid: d.uuid, serialNumber: d.serialNumber });
    } catch (err) {
      setError(err instanceof Error ? err.message : String(err));
    }
  };
```

--------------------------------

### login

Source: https://docs.plaud.ai/plaud-mcp-cli/mcp

Initiates the OAuth sign-in process by opening the browser.

```APIDOC
## login

### Description
Opens your browser for OAuth sign-in.
```

--------------------------------

### Execute IBleAgent Command with Callbacks

Source: https://docs.plaud.ai/plaud-embedded/advanced-android-sdk

Use OnRequest and OnResponse callbacks to handle command transmission and device replies.

```kotlin
ble.getStorage(
    object : AgentCallback.OnRequest {
        override fun onRequestResult(success: Boolean, code: Int, msg: String?) {
            // the command reached the device (or didn't)
        }
    },
    object : AgentCallback.OnResponse<StorageRsp> {
        override fun onResponse(rsp: StorageRsp) {
            // the device replied — typed response object, not primitives
        }
    }
)
```

--------------------------------

### Clone Plaud Embedded Repository

Source: https://docs.plaud.ai/plaud-embedded/flutter

Clone the official Plaud Embedded Flutter repository to access the plugin and example app.

```bash
git clone https://github.com/Plaud-AI/embedded_flutter.git
```

--------------------------------

### Configure local.properties

Source: https://docs.plaud.ai/plaud-embedded/android-starter-app

Define environment variables for SDK initialization and API access in the local.properties file.

```properties
sdk.dir=/path/to/your/Android/sdk

# Required for SDK initialization
PLAUD_USER_ACCESS_TOKEN=your-jwt-token

# Required for Transcription API (optional, not needed for device features)
PLAUD_CLIENT_ID=your-client-id
PLAUD_API_KEY=your-api-key
```

--------------------------------

### Initialize Plaud Device SDK

Source: https://docs.plaud.ai/plaud-embedded/ios-sdk

Perform the SDK initialization with the user access token and regional domain.

```swift
import PlaudDeviceBasicSDK

PlaudDeviceAgent.shared.initSDK(
    userAccessToken: "user-token",
    customDomain: "platform-us.plaud.ai"  // domain only, no https://
)
```

--------------------------------

### GET https://platform-us.plaud.ai/developer/api/open/partner/ai/transcriptions/[TRANSCRIPTION_ID]

Source: https://docs.plaud.ai/plaud-embedded/transcription-api-overview

Check the status of your transcription task. On the SUCCESS status code, the transcript data will be included.

```APIDOC
## GET https://platform-us.plaud.ai/developer/api/open/partner/ai/transcriptions/[TRANSCRIPTION_ID]

### Description
Check the status of your transcription task. On the SUCCESS status code, the transcript data will be included.

### Method
GET

### Endpoint
https://platform-us.plaud.ai/developer/api/open/partner/ai/transcriptions/[TRANSCRIPTION_ID]

### Parameters
#### Path Parameters
- **TRANSCRIPTION_ID** (string) - Required - The ID of the transcription task to poll

### Response
#### Success Response (200)
- **transcription_id** (string) - The ID of the task
- **status** (string) - The current status of the task (e.g., SUCCESS)
- **data** (object) - The transcribed data including text, language, duration, and segments
```

--------------------------------

### PlaudDeviceAgent.initSDK

Source: https://docs.plaud.ai/plaud-embedded/android-sdk

Initializes the Plaud SDK singleton with the application context, user access token, and regional domain.

```APIDOC
## PlaudDeviceAgent.initSDK

### Description
Initializes the SDK with the required application context, user authentication token, and regional server domain.

### Parameters
- **context** (Context) - Required - Your application Context (e.g. applicationContext).
- **userAccessToken** (String) - Required - User Access Token (JWT), used for device authentication.
- **customDomain** (String) - Required - Your regional Plaud server domain without https:// prefix.
```

--------------------------------

### OpenAPI Specification for Get User Token

Source: https://docs.plaud.ai/api-reference/authentication-api/get-user-token

Defines the POST endpoint for exchanging partner tokens for user-specific access tokens.

```yaml
openapi: 3.0.4
info:
  title: Authentication Tokens
  description: >-
    Retrieve your Partner and User tokens to start using the Embedded SDK and
    Transcription API
  version: 0.0.1
servers:
  - url: https://platform-us.plaud.ai/developer/api
    description: US partner endpoint
  - url: https://platform-jp.plaud.ai/developer/api
    description: Japan partner endpoint
security: []
paths:
  /open/partner/users/access-token:
    post:
      tags:
        - Authentication API
      summary: Get User Token
      description: >-
        User-level token. Exchange a partner access token for a per-user access
        token. This is the token the Embedded SDK and file upload endpoints
        accept.
      operationId: createUserAccessToken
      parameters:
        - $ref: eda4df56-3533-423b-aad0-5829e5ab6c45
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - user_id
              properties:
                user_id:
                  type: string
                  description: Your stable identifier for the user.
                  minLength: 6
                  maxLength: 120
                expires_in:
                  type: integer
                  description: Requested lifetime of the user access token, in seconds.
                  example: 86400
            example:
              user_id: <your stable user id, 6-120 chars>
              expires_in: 86400
      responses:
        '200':
          description: User access token issued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserTokenResponse'
              example:
                access_token: eyJhbGci...
                token_type: bearer
                expires_in: 86400
      security:
        - bearerAuth: []
components:
  schemas:
    UserTokenResponse:
      type: object
      properties:
        access_token:
          type: string
          description: The user access token.
        token_type:
          type: string
          description: The token type.
          example: bearer
        expires_in:
          type: integer
          description: Lifetime of the access token, in seconds.
          example: 86400
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer authentication using a partner access token.
```

--------------------------------

### Initialize and Use Plaud SDK in Dart

Source: https://docs.plaud.ai/plaud-embedded/flutter

Initialize the SDK and handle device scanning, connection, and file export streams.

```dart
import 'package:plaud_sdk/plaud_sdk.dart';

if (!isPlaudSdkAvailable) { /* off-device: show a "device required" state */ }

await PlaudSdk.initSDK(
  userAccessToken: token,               // per-user Bearer JWT
  customDomain: 'platform-us.plaud.ai', // domain only, no https://
  userId: 'your-app-user-id',           // default connect deviceToken
);

final subs = <StreamSubscription>[
  PlaudSdk.onScanResult.listen((devices) {/* show devices */}),
  PlaudSdk.onConnectState.listen((s) {
    if (s.connected) PlaudSdk.getFileList();   // load recordings on connect
  }),
  PlaudSdk.onFileList.listen((files) {/* show recordings */}),
  PlaudSdk.onExportProgress.listen((p) {/* p.progress (0–100), p.message */}),
];

await PlaudSdk.startScan();
await PlaudSdk.connectBleDevice(uuid: device.uuid);   // from an onScanResult device
final export = await PlaudSdk.exportAudio(
  sessionId: file.sessionId,
  format: PlaudAudioFormat.mp3,
);
// export.outputPath → the decoded mp3 under Documents/PlaudExports

for (final s in subs) { s.cancel(); }
```

--------------------------------

### Modify App Name in strings.xml

Source: https://docs.plaud.ai/plaud-embedded/android-starter-app

Update the application name and onboarding text strings.

```xml
<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="app_name">Plaud Template</string>

    <!-- Onboarding -->
    <string name="welcome_app_name">App name</string>
    <string name="get_started">Get Started</string>
    <string name="connect_later">Connect device later</string>
```

--------------------------------

### Add Plaud Embedded Skill

Source: https://docs.plaud.ai/plaud-embedded/quickstart

Use this command to add the Plaud Embedded skill to your coding agent for guided assistance.

```bash
npx skills add Plaud-AI/plaud-embedded-skills
```

--------------------------------

### Prebuild Expo Project

Source: https://docs.plaud.ai/plaud-embedded/react-native

Run expo prebuild to generate native project files for iOS and Android.

```bash
npx expo prebuild -p ios
npx expo prebuild -p android
```

--------------------------------

### Clone the Embedded Capacitor repository

Source: https://docs.plaud.ai/plaud-embedded/web-app-wrapper

Initial step to retrieve the demo application source code from GitHub.

```bash
git clone https://github.com/Plaud-AI/embedded-capacitor.git
```

--------------------------------

### Troubleshoot 'plaud: command not found'

Source: https://docs.plaud.ai/plaud-mcp-cli/cli

If the `plaud` command is not found, try reopening your terminal and ensure the global npm installation completed successfully.

```bash
plaud: command not found
```

--------------------------------

### POST /open/partner/ai/transcriptions/

Source: https://docs.plaud.ai/api-reference/transcription-api/submit-audio-for-transcription

Submit an audio file for transcription. Pass the pre-signed download URL returned by complete-upload. Transcription runs asynchronously — use the returned transcription_id to poll for results.

```APIDOC
## POST /open/partner/ai/transcriptions/

### Description
Submit an audio file for transcription. Pass the pre-signed download URL returned by complete-upload. Transcription runs asynchronously — use the returned `transcription_id` to poll for results.

### Method
POST

### Endpoint
/open/partner/ai/transcriptions/

### Parameters
#### Request Body
- **file_url** (string) - Required - Pre-signed download URL returned by complete-upload (M4A, MP3, WAV).
- **params** (object) - Optional - Optional transcription parameters.

### Request Example
{
  "file_url": "<DownloadUrl from file upload>",
  "params": {
    "transcribe": {
      "language": "auto"
    },
    "vad": {
      "decode_silence": false
    },
    "diarization": {
      "enabled": false,
      "return_embedding": false
    }
  }
}

### Response
#### Success Response (200)
- **transcription_id** (string) - Identifier used to poll for results.
- **status** (string) - The current status of the task (PENDING, RECEIVED, STARTED, PROGRESS, SUCCESS, FAILURE, REVOKED).
- **data** (object) - Empty until the transcription completes.

#### Response Example
{
  "transcription_id": "task_exec_xxx",
  "status": "PENDING",
  "data": {}
}
```

--------------------------------

### Troubleshoot npx E404 Error for Plaud AI CLI

Source: https://docs.plaud.ai/plaud-mcp-cli/cli

If `npx` returns an `E404` error for `@plaud-ai/cli`, clear your npm cache and retry the installation.

```bash
npm cache clean --force
```

--------------------------------

### Run App on Device

Source: https://docs.plaud.ai/plaud-embedded/react-native

Build and run the application on physical iOS and Android devices.

```bash
npx expo prebuild -p ios
npx expo run:ios --device

npx expo prebuild -p android
npx expo run:android --device
```

--------------------------------

### Generate Presigned URLs Response Example

Source: https://docs.plaud.ai/api-reference/file-upload-api/generate-presigned-upload-urls

The response provides a file identifier, upload session ID, chunk size, and an array of parts containing presigned URLs.

```json
{
  "FileId": "file_xxx",
  "UploadId": "upload_xxx",
  "ChunkSize": 5242880,
  "Parts": [
    {
      "PartNumber": 1,
      "PresignedUrl": "https://plaud-bucket.s3.amazonaws.com/..."
    },
    {
      "PartNumber": 2,
      "PresignedUrl": "https://plaud-bucket.s3.amazonaws.com/..."
    }
  ]
}
```

--------------------------------

### Customize Welcome Screen Branding

Source: https://docs.plaud.ai/plaud-embedded/ios-starter-app

Update the logo image and application name label in the WelcomeViewController.

```swift
    private let logoIcon: UIImageView = {
        let iv = UIImageView(image: UIImage(systemName: "square.grid.2x2")) // [!code --]
        iv.tintColor = .label//[!code --]
        let iv = UIImageView(image: UIImage(named: "your-icon"))// [!code ++]
        iv.contentMode = .scaleAspectFit
        iv.translatesAutoresizingMaskIntoConstraints = false
        return iv
    }()
    /// App name label (B2B customers replace with their own brand name)
    private let appNameLabel: UILabel = {
        let l = UILabel()
        l.text = "App name"//[!code --]
        l.text = "Your App Name!"//[!code ++]
        l.font = PlaudTheme.largeTitle()
```

--------------------------------

### Complete Multipart Upload Request Example

Source: https://docs.plaud.ai/api-reference/file-upload-api/complete-multipart-upload

JSON payload required to complete a multipart upload, including the file ID, upload ID, and the list of parts with their respective ETags.

```json
{
  "file_id": "file_xxx",
  "upload_id": "upload_xxx",
  "part_list": [
    {
      "PartNumber": 1,
      "ETag": "\"abc123...\""
    },
    {
      "PartNumber": 2,
      "ETag": "\"def456...\""
    }
  ],
  "filetype": "mp3",
  "file_md5": "9e107d9d372bb6826bd81d3542a419d6"
}
```

--------------------------------

### Implement WiFi File Synchronization

Source: https://docs.plaud.ai/plaud-embedded/advanced-ios-sdk

Configures the WiFiAgent delegate and handles the handshake process to initiate file listing and synchronization.

```swift
import PlaudDeviceBasicSDK

WiFiAgent.shared.delegate = self
WiFiAgent.shared.bleDevice = BleAgent.shared.bleDevice   // required before connecting

// From bleWiFiOpen(_:_:_:_:) on PlaudDeviceAgentProtocol:
WiFiAgent.shared.connectWifi(wifiName, wifiPass, 60)

extension SyncManager: WiFiAgentProtocol {
    func wifiHandshake(_ status: Int) {
        guard status == 0 else { return }
        WiFiAgent.shared.appGetFileList(Int(Date().timeIntervalSince1970), 0, false)
    }
    func wifiFileList(_ files: [BleFile]) {
        guard let file = files.first else { return }
        WiFiAgent.shared.appSyncFile(file.sessionId, 0, 0, file.scenes)
    }
    func wifiSyncFileData(_ sessionId: Int, _ offset: Int, _ count: Int, _ binData: Data) {
        // append binData at offset
    }
    func wifiDataComplete() { /* all bytes received */ }
}
```

--------------------------------

### Configure Gradle Dependencies

Source: https://docs.plaud.ai/plaud-embedded/web-app-wrapper

Add the required SDK dependencies to your build.gradle file.

```gradle
        implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlinVersion"
        implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:$coroutinesVersion"
        implementation "com.squareup.okhttp3:okhttp:$okhttpVersion"
        implementation "com.squareup.okhttp3:logging-interceptor:$okhttpVersion"
        implementation "com.squareup.retrofit2:retrofit:$retrofitVersion"
        implementation "com.squareup.retrofit2:converter-gson:$retrofitVersion"
        implementation "com.google.code.gson:gson:$gsonVersion"
        implementation "com.google.guava:guava:$guavaVersion"
        implementation "org.bouncycastle:bcprov-jdk18on:$bouncyCastleVersion"
        implementation "com.java-websocket:Java-WebSocket:$javaWebSocketVersion"
        implementation "org.slf4j:slf4j-api:$slf4jVersion"
        implementation "com.github.tony19:logback-android:$logbackAndroidVersion"
        implementation "com.jakewharton.timber:timber:$timberVersion"

        // ...leave the rest of the generated block (capacitor-android, androidx, tests) as-is
    }
```

--------------------------------

### Clone the Plaud SDK repository

Source: https://docs.plaud.ai/plaud-embedded/ios-sdk

Initial step to obtain the SDK source files from the public repository.

```bash
git clone https://github.com/Plaud-AI/plaud-sdk-public.git
```

--------------------------------

### Download Firmware Update in Kotlin

Source: https://docs.plaud.ai/plaud-embedded/android-sdk

Downloads the firmware file and performs MD5 verification, reporting progress through the callback.

```kotlin
// Download + MD5 verify
PlaudDeviceAgent.downloadFirmware(updateInfo, object : SimpleFirmwareUpdateCallback() {
    override fun onDownloadProgress(progress: UpdateProgress) {
        // progress.progress: 0 ~ 100
    }
    override fun onDownloadComplete(result: FirmwareDownloadResult) {
        if (result.success) {
            result.file?.let { /* install (below) */ }
        }
    }
})
```

--------------------------------

### Connect and Bind Device over BLE

Source: https://docs.plaud.ai/plaud-embedded/android-sdk

Prepare the device for connection by ensuring RSA keys are ready and the serial number is signed.

```kotlin
import sdk.NiceBuildSdk

private fun connect(bleDevice: BleDevice) = lifecycleScope.launch(Dispatchers.IO) {
    val sn = bleDevice.serialNumber ?: return@launch
    val deviceType = if (sn.startsWith("881")) "notepro" else "notepins"

    // 1. Wait for the RSA key pair fetched by initSDK.
    val deadline = System.currentTimeMillis() + 10_000L
    while (!NiceBuildSdk.isPartnerDataReady() && System.currentTimeMillis() < deadline) {
        delay(200)
    }

    // 2. Sign the SN — the handshake reads the stored signature.
    if (!NiceBuildSdk.signAndStoreDeviceSn(deviceType, sn)) {
        // network unreachable or token rejected — the handshake will fail
    }

    PlaudDeviceAgent.connectBleDevice(bleDevice)
}
```

--------------------------------

### Retrieve File List and Export Audio

Source: https://docs.plaud.ai/plaud-embedded/android-sdk

Use getFileList to access device files and exportAudio to transfer recordings to the local directory. Ensure the callback handles progress updates and completion events.

```kotlin
// Get file list from device
PlaudDeviceAgent.getFileList()

PlaudDeviceAgent.exportAudio(
    sessionId = sessionId,
    outputDir = outputDir,
    format = AudioExportFormat.WAV,
    channels = 1,
    callback = object : AudioExporter.ExportCallback {
        override fun onProgress(progress: Int, message: String) { }
        override fun onComplete(outputFile: File) {
            // decoded file is ready at outputFile
        }
    }
)
```

--------------------------------

### Connect to Device via IBleAgent

Source: https://docs.plaud.ai/plaud-embedded/advanced-android-sdk

Perform manual device scanning and connection using the low-level IBleAgent API.

```kotlin
val ble = TntAgent.getInstant().bleAgent

TntAgent.getInstant().addBleAgentListeners(myBleAgentListener)
ble.scanBle(true)

// From scanBleDeviceReceiver(...) on your BleAgentListener:
ble.connectionBLE(
    device,                                          // the scanned BleDevice
    NiceBuildSdk.resolveHandshakeToken(userJwt),     // handshake token from the JWT `sub`
    deviceToken,                                     // your per-device token
    "",                                              // userName
    false                                            // isForceClear
)
```

--------------------------------

### Initialize PlaudDeviceAgent

Source: https://docs.plaud.ai/plaud-embedded/android-sdk

Initialize the singleton PlaudDeviceAgent with your application context, user token, and regional domain. Assign a listener to handle device events.

```kotlin
import sdk.PlaudDeviceAgent

// Initialize once with your app Context, user token, and regional domain
PlaudDeviceAgent.initSDK(
    context = applicationContext,
    userAccessToken = "user-token",
    customDomain = "platform-us.plaud.ai"  // domain only, no https://
)

// Assign the global listener to receive device events
PlaudDeviceAgent.listener = object : PlaudDeviceAgentListener {
    override fun blePenState(state: Int, privacy: Int, keyState: Int, uDisk: Int) {
        // handshake complete — device is ready
    }
    // override only the callbacks you need
}
```

--------------------------------

### Add and Sync Platforms

Source: https://docs.plaud.ai/plaud-embedded/web-app-wrapper

Add iOS and Android platforms to your Capacitor project and sync the web assets.

```bash
//For ios
npx cap add ios
npx cap sync ios

//For android
npx cap add android
npx cap sync android
```

--------------------------------

### Device State and Configuration

Source: https://docs.plaud.ai/plaud-embedded/advanced-ios-sdk

Methods for reading device status and updating system settings.

```APIDOC
## Device State Methods
- **getState()**: Retrieves current device state.
- **getStorage()**: Retrieves storage information.
- **getChargingState()**: Retrieves battery charging status.
- **readPower()**: Reads current power levels.
- **getDeviceStatus()**: Retrieves general device status.

## Configuration Methods
- **setHeartBeat(status: Int)**: Sets the device heartbeat status.
- **setDeviceActive(status: Int)**: Sets the device active state.
- **setPrivacy(onOff: Int)**: Toggles privacy mode.
- **restoreFactory()**: Resets the device to factory settings.
```

--------------------------------

### PlaudDeviceAgent.startWifiTransfer

Source: https://docs.plaud.ai/plaud-embedded/android-sdk

Initiates a WiFi transfer session.

```APIDOC
## PlaudDeviceAgent.startWifiTransfer(userId: String, callback: IWifiTransferAgent.WifiTransferCallback)

### Description
Starts the WiFi transfer session after the device hotspot is ready. The SDK handles the connection and handshake.

### Parameters
- **userId** (String) - Required - Identifier for the transfer session.
- **callback** (IWifiTransferAgent.WifiTransferCallback) - Required - Callback to handle connection states and file events.
```

--------------------------------

### Copy and Configure Plaud Plugin

Source: https://docs.plaud.ai/plaud-embedded/flutter

Copy the plugin files and update the pubspec.yaml to include the local dependency.

```bash
cp -R plugins/plaud_sdk your-app/plugins/plaud_sdk
```

```yaml
dependencies:
  plaud_sdk:
    path: plugins/plaud_sdk
```

```bash
flutter pub get
```
Tokens:
Raw