Add Symbl Sapat transcription guide

Signed-off-by: jtc268 <89586838+jtc268@users.noreply.github.com>

Author: jtc268

articles/20260527_run_symbl_transcription_with_sapat_in_daytona.md

@@ -0,0 +1,321 @@
+---
+title: "Run Symbl.ai Transcription With Sapat"
+description:
+  "Use Daytona, Sapat, and Symbl.ai to run a reproducible async audio
+  transcription workflow for video files."
+date: 2026-05-27
+author: "jtc268"
+tags: ["daytona", "sapat", "symbl-ai", "transcription"]
+---
+
+# Run Symbl.ai Transcription With Sapat
+
+# Introduction
+
+Video transcription usually starts as a small utility task. One meeting recording
+needs notes. One product demo needs a searchable transcript. One interview needs
+to become a written brief before the team forgets the details. The work feels
+simple until the same command must run on another machine, with another API key,
+against a larger recording, inside a clean environment.
+
+This guide shows how to run a reproducible transcription workflow with
+[Daytona](https://www.daytona.io/), [Sapat](https://github.com/nkkko/sapat), and
+Symbl.ai. The companion Sapat implementation is open at
+[nibzard/sapat#52](https://github.com/nibzard/sapat/pull/52). It adds
+`--api symbl`, submits converted MP3 audio to Symbl.ai's async audio workflow,
+polls the returned job, retrieves conversation messages, and writes the final
+transcript into Sapat's existing `.txt` output path.
+
+![Sapat Symbl.ai transcription flow in Daytona](assets/20260527_run_symbl_transcription_with_sapat_in_daytona.svg)
+
+## TL;DR
+
+- Use Daytona to keep Python, ffmpeg, dependencies, and environment variables in
+  one reproducible workspace.
+- Use Sapat to convert `.mp4` files to MP3 and route transcription through
+  `--api symbl`.
+- Use Symbl.ai's [async audio API](../definitions/20260527_definition_async_audio_api.md)
+  pattern for longer recorded conversations: submit audio, poll the job, then
+  fetch the transcript messages.
+- Keep credentials in `.env` or Daytona workspace environment variables. Do not
+  commit API keys, audio files, or generated transcripts.
+
+## Prerequisites
+
+You need:
+
+- A Daytona workspace that can open the Sapat repository.
+- Python 3.10 or newer for the commands in this guide.
+- `ffmpeg` installed in the workspace.
+- A Symbl.ai account with either a temporary access token or an app ID and app
+  secret.
+- A video file in `.mp4` format for the sample run.
+
+The provider in the companion PR does not require the Symbl Python SDK. It uses
+the same `requests` dependency that Sapat already uses for its OpenAI and Groq
+providers.
+
+## Step 1: Create a Daytona Workspace
+
+Start from the Sapat repository. Daytona will provision a clean workspace around
+the repository so the setup can be repeated without relying on local laptop
+state.
+
+```bash
+daytona create https://github.com/nkkko/sapat --code
+```
+
+After the workspace opens, confirm the project has the expected shape:
+
+```bash
+ls
+```
+
+You should see files such as `README.md`, `pyproject.toml`, `requirements.txt`,
+and the `src/sapat` package. If you are testing the Symbl provider before it is
+merged upstream, check out the companion PR branch or apply the patch from
+[nibzard/sapat#52](https://github.com/nibzard/sapat/pull/52).
+
+## Step 2: Install Dependencies
+
+Create an isolated virtual environment inside the Daytona workspace:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+Sapat calls `ffmpeg` to turn video into MP3 before it sends audio to a provider.
+Check that `ffmpeg` is available:
+
+```bash
+ffmpeg -version
+```
+
+If the command is missing, install it in the workspace image or through the
+package manager available in your Daytona environment. For Debian-based
+workspaces, the usual command is:
+
+```bash
+sudo apt-get update
+sudo apt-get install -y ffmpeg
+```
+
+## Step 3: Configure Symbl.ai Credentials
+
+The Symbl provider supports two credential modes.
+
+Use an existing access token:
+
+```bash
+cat > .env <<'EOF'
+SYMBL_ACCESS_TOKEN=replace_with_your_access_token
+SYMBL_API_BASE_URL=https://api.symbl.ai/v1
+SYMBL_JOB_POLL_INTERVAL_SECONDS=5
+SYMBL_JOB_TIMEOUT_SECONDS=600
+EOF
+```
+
+Or let Sapat generate an access token from an app ID and app secret:
+
+```bash
+cat > .env <<'EOF'
+SYMBL_APP_ID=replace_with_your_app_id
+SYMBL_APP_SECRET=replace_with_your_app_secret
+SYMBL_API_BASE_URL=https://api.symbl.ai/v1
+SYMBL_JOB_POLL_INTERVAL_SECONDS=5
+SYMBL_JOB_TIMEOUT_SECONDS=600
+EOF
+```
+
+Keep `.env` out of source control. The Sapat repository already ignores `.env`,
+and the companion PR adds the Symbl variable names to `.env.example` with
+placeholder values only.
+
+Symbl.ai's public docs describe the async audio flow as a three-step process:
+submit recorded audio, check the job status, and use the returned conversation
+ID to retrieve messages from the Conversations API. The provider follows that
+same shape so the Sapat command can stay simple.
+
+## Step 4: Run Sapat With Symbl.ai
+
+Put a test video in the workspace. For this example, assume the file is named
+`demo.mp4`.
+
+Run Sapat with the Symbl provider:
+
+```bash
+sapat demo.mp4 --quality M --language en --api symbl
+```
+
+Behind the scenes, Sapat performs the following steps:
+
+| Step | What happens |
+| --- | --- |
+| Convert | `ffmpeg` creates `demo.mp3` next to the input video. |
+| Submit | Sapat posts the MP3 file to Symbl.ai's async audio endpoint. |
+| Poll | Sapat polls the returned job ID until it is complete or times out. |
+| Retrieve | Sapat fetches conversation messages and joins them into transcript text. |
+| Save | Sapat writes `demo.txt` and removes the temporary MP3 file. |
+
+When the run finishes, open the transcript:
+
+```bash
+sed -n '1,80p' demo.txt
+```
+
+For a directory of recordings, point Sapat at the directory:
+
+```bash
+sapat recordings/ --quality M --language en --api symbl
+```
+
+Sapat processes `.mp4` files in that directory and writes one `.txt` file for
+each video.
+
+## Step 5: Tune the Workflow
+
+The default polling settings are conservative:
+
+```bash
+SYMBL_JOB_POLL_INTERVAL_SECONDS=5
+SYMBL_JOB_TIMEOUT_SECONDS=600
+```
+
+Use a shorter polling interval while testing small files. Use a longer timeout
+for long meetings or classes. The timeout should reflect your expected audio
+length and the service latency you see in practice.
+
+For language, Sapat accepts simple values such as `en`, `es`, `fr`, or a full
+BCP-47 code such as `en-US`. The provider maps common short language names to
+Symbl.ai language codes and passes full codes through unchanged.
+
+## How the Symbl.ai Provider Fits Sapat
+
+Sapat's existing provider model is intentionally small. Every provider receives
+the converted MP3 path and returns transcript text or a JSON object containing a
+`text` field. That means a provider can use a synchronous API such as OpenAI's
+audio transcription endpoint or an async flow such as Symbl.ai without changing
+the command a user runs.
+
+The Symbl provider keeps that contract. It handles the longer async lifecycle
+inside the provider class:
+
+1. It checks that the converted audio file exists.
+2. It resolves credentials from `SYMBL_ACCESS_TOKEN` or generates a token from
+   `SYMBL_APP_ID` and `SYMBL_APP_SECRET`.
+3. It posts the MP3 bytes to `/process/audio` with a `languageCode` query
+   parameter.
+4. It stores the returned `jobId` and `conversationId`.
+5. It polls `/job/{jobId}` until the job is complete, failed, or timed out.
+6. It calls `/conversations/{conversationId}/messages` and joins message text
+   into the transcript returned to Sapat.
+
+This shape keeps the user experience stable. The command remains:
+
+```bash
+sapat demo.mp4 --api symbl
+```
+
+The only difference is that the provider may wait while Symbl.ai processes the
+recording. That wait is why the timeout setting matters.
+
+## When to Use This Provider
+
+Use the Symbl.ai route when your workflow benefits from an async conversation
+pipeline rather than a one-shot transcription response. Meeting recordings,
+customer interviews, research calls, lectures, and webinar recordings are good
+fits because they often become more useful when the transcript is tied to a
+conversation identifier and can later support richer conversation intelligence.
+
+For quick one-off clips, another provider may be simpler. For private local
+transcription, an offline provider may be a better fit. The advantage of keeping
+Symbl.ai behind Sapat's `--api` option is that your team can switch providers
+without changing the file layout, Daytona workspace, or transcript destination.
+
+## Operational Guardrails
+
+Treat recorded conversations as sensitive data. Keep raw videos, generated MP3
+files, and transcripts out of Git unless you have a deliberate publishing
+workflow. A clean pattern is:
+
+- Store input recordings in a private workspace folder.
+- Run Sapat from that folder.
+- Review the generated `.txt` file before sharing it.
+- Move approved transcripts into the system that needs them.
+- Delete temporary or test recordings when the review is done.
+
+If multiple teammates use the same Daytona workspace template, document the
+required environment variables but not the values. The `.env.example` file should
+show names and safe placeholders only. Secrets should come from each developer's
+workspace environment or secret manager.
+
+## Step 6: Validate Before Sharing
+
+Before opening a PR or handing this workflow to teammates, run checks that prove
+the provider is wired correctly:
+
+```bash
+PYTHONPATH=src python -m unittest discover -s tests -v
+PYTHONPATH=src python -m compileall src tests
+PYTHONPATH=src python -m sapat.script --help
+git diff --check
+```
+
+The mocked provider tests in the companion PR cover:
+
+- Submitting an MP3 file with the expected bearer token and content type.
+- Converting a short `en` language flag into `en-US`.
+- Polling an in-progress job until it completes.
+- Reading conversation messages into a final transcript string.
+- Generating an access token from `SYMBL_APP_ID` and `SYMBL_APP_SECRET`.
+- Raising an error when the async job fails.
+
+These tests do not upload private audio and do not require live Symbl.ai
+credentials.
+
+## Common Issues and Troubleshooting
+
+**Problem:** `ffmpeg` is not found.
+
+**Solution:** Install `ffmpeg` in the Daytona workspace and rerun the command.
+Sapat cannot submit to Symbl.ai until it has converted the video to MP3.
+
+**Problem:** The command says `Set SYMBL_ACCESS_TOKEN or both SYMBL_APP_ID and
+SYMBL_APP_SECRET`.
+
+**Solution:** Confirm `.env` exists in the Sapat project root and that your
+terminal session loads it from that directory. Do not commit this file.
+
+**Problem:** The job times out.
+
+**Solution:** Increase `SYMBL_JOB_TIMEOUT_SECONDS`. If the file is unusually
+large, test with a shorter clip first so you can confirm credentials and provider
+wiring before running the full recording.
+
+**Problem:** The transcript is empty.
+
+**Solution:** Check the Symbl.ai job status in your provider logs and confirm the
+conversation messages endpoint returns message objects with `text` fields. Also
+check that the audio is audible after conversion.
+
+## Conclusion
+
+Daytona gives the workflow a clean workspace. Sapat gives it a small command
+surface. Symbl.ai gives it an async transcription path for recorded audio. Put
+together, the setup is easy to rerun: create the workspace, install dependencies,
+set credentials, run `sapat --api symbl`, and verify the `.txt` transcript.
+
+That repeatability is the main win. The same flow works for one demo recording,
+a batch of class videos, or a set of customer interviews, without requiring each
+developer to rediscover the provider wiring on their own machine.
+
+## References
+
+- [Sapat repository](https://github.com/nkkko/sapat)
+- [Companion Symbl.ai provider PR](https://github.com/nibzard/sapat/pull/52)
+- [Symbl.ai transcription overview](https://symbl.ai/platform/understanding-apis/transcription/)
+- [Symbl.ai process conversation overview](https://docs.symbl.ai/docs/overview-process-a-conversation)
+- [Symbl.ai supported languages](https://docs.symbl.ai/docs/supported-languages)
+- [Symbl.ai async audio example](https://symbl.ai/developers/blog/use-async-audio-api-in-your-react-app/)

articles/assets/20260527_run_symbl_transcription_with_sapat_in_daytona.svg

@@ -0,0 +1,10 @@
+Author: jtc268
+Title: Independent Developer
+Description: jtc268 works on practical developer tooling, automation, and
+open-source integrations, with a focus on reproducible workflows that can be
+verified from code, tests, and clear runbooks.
+Company Name: Independent
+Company Description: Independent open-source contributor.
+Author Image: [https://avatars.githubusercontent.com/u/89586838?v=4]
+Company Logo Dark:
+Company Logo White:

authors/jtc268.md

@@ -0,0 +1,20 @@
+---
+title: "Async audio API"
+description:
+  "An async audio API accepts recorded audio, processes it as a background job,
+  and returns transcript data after the job completes."
+date: 2026-05-27
+author: "jtc268"
+tags: ["audio", "transcription", "api"]
+---
+
+# Async audio API
+
+An async audio API processes recorded audio outside the original request and
+returns a job or conversation identifier that clients can poll or receive
+through a webhook. This pattern is useful when audio files are too large or too
+slow to transcribe during a single HTTP request.
+
+In a transcription workflow, the client uploads or links to an audio file, stores
+the returned job ID, waits until processing completes, and then fetches the
+transcript or conversation messages from a follow-up endpoint.