mcpField
P
plaud-embedded-transcription-api-skill

plaud-embedded-transcription-api-skill

github.com/plaud-aiProductivity1375 installsUpdated 3w ago
Repository

About plaud-embedded-transcription-api-skill

An API guidance skill for developers using Plaud's transcription pipeline. It explains how to submit audio URLs, poll asynchronous jobs, and configure options such as language detection and speaker diarization.

Key features

  1. 01Guide audio transcription submission
  2. 02Explain asynchronous status polling
  3. 03Describe multipart file uploads
  4. 04Configure language and detection level
  5. 05Enable speaker labels and embeddings
  6. 06Explain transcription result fields

Use cases

  1. 01Transcribe audio with a public download URL
  2. 02Upload audio before submitting transcription
  3. 03Poll jobs and retrieve aligned text
  4. 04Set transcription language or speaker diarization

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/plaud-ai/plaud-embedded-skills --skill plaud-embedded-transcription-api-skill

After installing, type/plaud-embedded-transcription-api-skillin Claude Code to confirm it loaded.

Details

From the project README

Plaud Embedded Transcription API Skill

This skill provides context and instructions on how to upload audio files to Plaud for transcription.

When To Use This Skill

Use this skill when a user wants to transcribe audio files using Plaud's Transcription Pipeline (the pipeline performs language detection, noise reduction, ASR, Speech-to-text, etc.)

Prerequisites
  • User has audio files on either:
    1. Their mobile app synced from a Plaud Device
    2. An audio file available for download on a public URL (i.e. S3 download URL)

How Plaud's Transcription API works

The Transcription API is an AI API with two main endpoints.

  1. Triggers an async transcription job given a file_url to download an audio file
  2. Get transcription task status for polling; On task finish, the conversation transcription will be available

How to Start Transcribing

The Transcription API itself requires a public download URL to download the audio file.

If the developer does not have a way to upload files and generate public download URLs already, use the File Upload API.

Else, skip the File Upload API and use the Transcription API directly.

File Upload API [ONLY FOR USERS WHO DO NOT HAVE A DOWNLOAD URL TO ACCESS THEIR AUDIO FILE]

The File Upload API is an API to use Plaud's cloud storage to upload audio files. This can be performed either from your mobile app or from your backend.

Read the File Upload Overview for the available File Upload API endpoints and data flow.

It is a 3-step multipart upload:

  1. POST /generate-presigned-urls with filesize and filetype → returns FileId, UploadId, ChunkSize, and a Parts array of presigned S3 URLs
  2. PUT up to ChunkSize of raw bytes to each PresignedUrl (no auth — these are presigned). Keep the ETag response header from every PUT — the next step needs them
  3. POST /complete-upload with file_id, upload_id, the part_list of PartNumber/ETag pairs, filetype, and file_md5 → returns the DownloadUrl

IMPORTANT: The returned DownloadUrl is valid for 24 hours. Pass it as file_url to the Transcription API.

API Reference (The Upload Step is not included as it's directly to S3)
Transcription API

After an audio file has been uploaded to a public download API (either via the File Upload API or through a user's unique cloud storage), the user can use the Transcription API on the file URL.

The Transcription API Overview goes through how Plaud's transcription flow works.

IMPORTANT: The Transcription API authenticates with your X-Client-Id and X-Client-Api-Key headers (the api_key is NOT your client_secret — grab it from the developer portal under App Settings > API Keys).

Supported audio formats for file_url are M4A, MP3, and WAV. Recordings exceeding 5 hours should be broken into chunks and transcribed in parts.

POST accepts an optional params object to tune the pipeline:

ParamDefaultPurpose
transcribe.languageautoBCP-47 code (en-US, zh-CN) or auto
transcribe.detection_levelsegmentLanguage identification level (segment or chapter)
vad.decode_silencefalseWhether to decode silent regions
diarization.enabledfalseIdentify and label speakers
diarization.return_embeddingfalseReturn speaker embedding vectors

Polling: the GET endpoint returns a status of PENDING, RECEIVED, STARTED, or PROGRESS while the task is in flight — keep polling. SUCCESS means data is populated. FAILURE and REVOKED are terminal failures — handle them rather than polling forever.

On SUCCESS, data carries text, language, duration (seconds), and an array of time-aligned segments (start, end, text, speaker_id when diarization is enabled, language, and a language-confidence probability).

API Reference

Reference Code

Definition of Done - Completed Implmentation of the Transcription API

When the user can:

  • (If the user does not have a public download URL already) Upload audio files from their mobile app to Plaud's managed storage via the File Upload API
  • Submit and get transcriptions for the Transcription API

Comments

Markdown supported