DEV Community: Dev Hunter

Building a Private, Offline Video Transcription Pipeline with Whisper AI

Dev Hunter — Wed, 09 Sep 2026 05:40:44 +0000

The Problem with Cloud Transcription

Most transcription tools today route your audio through someone else's server. That means:

Your interviews, meetings, and voice notes leave your machine
You pay per minute or per month
You hit rate limits on long files
You need an API key just to get started

For journalists, researchers, and content creators working with sensitive material, that's a non-starter. A confidential interview shouldn't pass through a third-party API before it reaches your transcript.

The alternative is to run speech-to-text locally. With OpenAI's Whisper model open-sourced under MIT, that's now practical on a mid-range laptop.

What We're Building

A Windows desktop workflow that:

Accepts a YouTube URL or a local audio/video file
Transcribes it fully offline using Whisper
Optionally switches to a cloud engine (Deepgram Nova-2) when speed matters more than privacy
Detects multiple speakers (diarization)
Exports to TXT, SRT, or DOCX

This is the architecture behind Video Transcriber Pro, a desktop tool I built to scratch my own itch — I needed to transcribe long research interviews without uploading them anywhere.

The Stack

Component	Choice	Why
Speech-to-text (local)	Whisper (openai-whisper)	MIT-licensed, runs on CPU or GPU
Speech-to-text (cloud)	Deepgram Nova-2	Fast, accurate, pay-per-use
Audio source	yt-dlp + ffmpeg	Pulls audio from YouTube, decodes files
Speaker diarization	pyannote.audio	Open-source, speaker segmentation
Text polish	Claude (optional)	Grammar, fluency, translation
Export	python-docx, srt	DOCX + SRT + plain text

Step 1: Pull Audio from a YouTube URL

The first hurdle is getting clean audio out of a YouTube video. yt-dlp handles this in a few lines:

import subprocess

def download_youtube_audio(url: str, output_path: str = "audio.mp3") -> str:
    subprocess.run([
        "yt-dlp",
        "-x",                       # extract audio only
        "--audio-format", "mp3",
        "--audio-quality", "0",     # best
        "-o", output_path,
        url
    ], check=True)
    return output_path

For local files, ffmpeg does the conversion to a Whisper-friendly format (16 kHz mono WAV):

def to_wav(input_path: str, output_path: str = "audio.wav") -> str:
    subprocess.run([
        "ffmpeg", "-y",
        "-i", input_path,
        "-ar", "16000",     # 16 kHz
        "-ac", "1",         # mono
        "-c:a", "pcm_s16le",
        output_path
    ], check=True)
    return output_path

The 16 kHz mono downmix matters. Whisper was trained on this format, and feeding it 48 kHz stereo audio noticeably degrades accuracy.

Step 2: Run Whisper Locally

The simplest path is the whisper Python package:

import whisper

model = whisper.load_model("medium")  # base, small, medium, large
result = model.transcribe("audio.wav", language="en")

print(result["text"])

For long files, you'll want to stream segments instead of holding the whole transcript in memory:

for segment in model.transcribe("audio.wav"):
    print(f"[{segment['start']:.1f}s] {segment['text']}")

Model size tradeoff:

Model	Size	Speed (CPU)	Accuracy
tiny	39M	Very fast	Low
base	74M	Fast	Medium
small	244M	Medium	Good
medium	769M	Slow	High
large	1550M	Very slow	Best

On a laptop with an RTX 4050, medium runs roughly 4x real-time on GPU. On CPU, expect closer to 0.3x real-time — fine for short clips, painful for 2-hour interviews.

Step 3: Speaker Diarization

Whisper gives you the words, but not who said them. pyannote.audio fills that gap:

from pyannote.audio import Pipeline

pipeline = Pipeline.from_pretrained(
    "pyannote/speaker-diarization-3.1",
    use_auth_token="YOUR_HF_TOKEN"
)
diarization = pipeline("audio.wav", min_speakers=2, max_speakers=5)

for turn, _, speaker in diarization.itertracks(yield_label=True):
    print(f"{turn.start:.1f}-{turn.end:.1f}s: {speaker}")

You then merge Whisper's segments with pyannote's speaker turns by timestamp overlap. The result is a transcript where each line is attributed:

[00:12.3 - 00:14.1] SPEAKER_00: So what made you start this project?
[00:14.5 - 00:19.8] SPEAKER_01: Mostly frustration with existing tools.

Step 4: Export to SRT (Subtitles)

SRT is just a text format with timestamps. Generating it from Whisper segments is straightforward:

def to_srt(segments, path: str):
    def fmt(t):
        h = int(t // 3600)
        m = int((t % 3600) // 60)
        s = int(t % 60)
        ms = int((t - int(t)) * 1000)
        return f"{h:02d}:{m:02d}:{s:02d},{ms:03d}"

    with open(path, "w", encoding="utf-8") as f:
        for i, seg in enumerate(segments, 1):
            f.write(f"{i}\n")
            f.write(f"{fmt(seg['start'])} --> {fmt(seg['end'])}\n")
            f.write(f"{seg['text'].strip()}\n\n")

For DOCX, python-docx writes the same content into a Word document with headings per speaker.

Step 5: Optional Cloud Mode (Deepgram Nova-2)

When privacy isn't a concern and you need speed, Deepgram's Nova-2 is hard to beat. The API is a single WebSocket call:

from deepgram import DeepgramClient

dg = DeepgramClient("YOUR_DEEPGRAM_KEY")
options = {
    "model": "nova-2",
    "smart_format": True,
    "diarize": True,
    "utterances": True,
}
response = dg.listen.prerecorded.v("1").transcribe_file({"buffer": audio_bytes}, options)

Nova-2 typically returns a 30-minute file in under 30 seconds. Whisper medium on GPU takes ~8 minutes for the same file. The tradeoff is clear: cloud for speed, local for privacy.

The Privacy Argument

This is the part that matters most for a lot of users:

Local mode: audio never leaves the machine. No API key, no upload, no usage logs on a third-party server.
Cloud mode: audio is sent to Deepgram, transcribed, and discarded per their retention policy.

For a journalist working with a confidential source, or a researcher handling IRB-protected interviews, only local mode is acceptable. That's why the tool defaults to Whisper and treats the cloud path as opt-in.

Where This Lives

I packaged this pipeline into a Windows desktop app so non-technical users can run it without touching a terminal:

Paste a YouTube URL or drag in a file
Pick local (Whisper) or cloud (Deepgram)
Click start
Export to TXT, SRT, or DOCX

It's called Video Transcriber Pro and it's a one-time purchase — no subscription, no per-minute billing. The local mode requires no API key at all.

If you just want the code, every piece above is open-source and composable. If you want the polished desktop version, that's the product.

FAQ

*Does local mode really need no internet?
After the first run (which downloads the Whisper model weights, ~1.5 GB for medium), yes — fully offline.

*How accurate is Whisper medium?
On clean English audio, word error rate is typically 5–8%. Noisy recordings and heavy accents degrade it, but that's true of every ASR system.

*Can I run this on a Mac or Linux?
The pipeline is pure Python and works cross-platform. The desktop app I linked is Windows-only because that's where most of my users are, but the underlying code runs anywhere ffmpeg and whisper do.

What about real-time transcription?
Whisper supports streaming via whisper-streaming or the faster-whisper backend. The desktop app currently does batch transcription; real-time is on the roadmap.

Takeaway

Speech-to-text is a solved problem technically. The open question is whether you're willing to upload your audio to solve it. With Whisper running locally, you don't have to — and you still get accuracy good enough for subtitles, meeting notes, and interview transcripts.

The code is open. The packaged app is product here if you want the desktop version.

If you found this useful, I write about AI tooling and agent architectures at dev.to/devhunterai.

ReAct Agent Loop from Scratch: Manual Implementation vs LangChain

Dev Hunter — Fri, 28 Aug 2026 17:45:46 +0000

What Is ReAct, and Why Should You Care?

ReAct (Reason + Act) is the pattern that powers virtually every modern AI agent. Instead of sending a single prompt to an LLM and hoping for the best, the agent loops:

Thought — the LLM reasons about what to do next
Action — it picks a tool to call
Observation — the tool's result is fed back into the conversation
Repeat — until the LLM produces a Final Answer

This loop is what separates a chatbot from an agent. A chatbot talks. An agent does things.

In this article, I'll walk you through a manual implementation of the ReAct loop in pure Python — about 170 lines — and then compare it with what LangChain gives you out of the box. You'll see exactly what the framework abstracts away, and where the abstraction leaks.

The Manual Implementation

The Tool System

Every agent needs tools. Here's a minimal but real tool registry:

from dataclasses import dataclass, field
from typing import Any, Callable
import json

@dataclass
class Tool:
    """A callable tool with metadata for the LLM."""
    name: str
    description: str
    func: Callable
    parameters: dict[str, Any] = field(default_factory=dict)

    def run(self, **kwargs: Any) -> str:
        result = self.func(**kwargs)
        return result if isinstance(result, str) else json.dumps(result)

Each tool has a name, a description (this is what the LLM reads to decide when to use it), the actual function, and a parameter schema.

Real tools look like this:

import httpx

def get_weather(city: str) -> str:
    """Fetch current weather for a city using Open-Meteo (no API key needed)."""
    geo = httpx.get(
        "https://geocoding-api.open-meteo.com/v1/search",
        params={"name": city, "count": 1, "language": "en", "format": "json"},
        timeout=10,
    ).json()

    if not geo.get("results"):
        return f"Could not find city: {city}"

    loc = geo["results"][0]
    lat, lon = loc["latitude"], loc["longitude"]

    weather = httpx.get(
        "https://api.open-meteo.com/v1/forecast",
        params={"latitude": lat, "longitude": lon, "current_weather": "true"},
        timeout=10,
    ).json()

    current = weather.get("current_weather", {})
    return (
        f"Weather in {loc['name']}, {loc.get('country', '')}: "
        f"{current.get('temperature', 'N/A')}°C, "
        f"wind {current.get('windspeed', 'N/A')} km/h"
    )

No API keys. No auth. Just a plain function that returns a string. That's all a tool needs to be.

The ReAct System Prompt

The entire intelligence of the loop comes from the system prompt. Here's the one I use:

REACT_SYSTEM_PROMPT = """You are an autonomous AI agent that solves tasks step by step.

You have access to the following tools:
{tool_descriptions}

Use this exact format:

Thought: reason about what to do next
Action: the tool name to call (one of [{tool_names}])
Action Input: the JSON input for the tool
Observation: the result of the tool

... (repeat Thought/Action/Action Input/Observation as needed)

Thought: I now know the final answer
Final Answer: the final answer to the original question

Rules:
- Always think before acting.
- Call one tool at a time.
- If a tool returns an error, try a different approach.
- When you have enough information, give the Final Answer.
"""

The format is strict on purpose. We're going to parse the LLM's output line by line, so we need it to follow the structure.

The Agent Loop

Here's the core — the actual ReAct loop:

class ReActAgent:
    def __init__(self, llm: str = "openai", tools=None, memory=None, max_steps: int = 8):
        self.llm = llm
        self.tools = tools or build_tool_registry()
        self.memory = memory or ConversationBufferMemory()
        self.max_steps = max_steps

    @staticmethod
    def _parse_action(text: str) -> tuple[str | None, str | None]:
        """Extract Action and Action Input from the LLM output."""
        action = None
        action_input = None

        for line in text.splitlines():
            line = line.strip()
            if line.startswith("Action:"):
                action = line.split("Action:", 1)[1].strip()
            elif line.startswith("Action Input:"):
                action_input = line.split("Action Input:", 1)[1].strip()

        return action, action_input

    def run(self, query: str) -> str:
        tool_descriptions = "\n".join(
            f"- {name}: {tool.description}" for name, tool in self.tools.items()
        )
        tool_names = ", ".join(self.tools.keys())

        system = REACT_SYSTEM_PROMPT.format(
            tool_descriptions=tool_descriptions, tool_names=tool_names
        )

        messages = [
            {"role": "system", "content": system},
            {"role": "user", "content": query},
        ]

        for step in range(self.max_steps):
            response = self._call_llm(messages)

            # Check if the LLM is done
            if "Final Answer:" in response:
                final = response.split("Final Answer:", 1)[1].strip()
                self.memory.add("assistant", final)
                return final

            # Parse the action
            action, action_input = self._parse_action(response)

            if not action or action not in self.tools:
                # Nudge the model back into the correct format
                messages.append({"role": "assistant", "content": response})
                messages.append({
                    "role": "user",
                    "content": (
                        "Invalid format or unknown tool. Use the exact format:\n"
                        "Thought: ...\nAction: <tool_name>\nAction Input: <json>"
                    ),
                })
                continue

            # Execute the tool
            try:
                kwargs = json.loads(action_input or "{}")
            except json.JSONDecodeError:
                kwargs = {"input": action_input}

            observation = self.tools[action].run(**kwargs)

            # Feed the observation back into the conversation
            messages.append({"role": "assistant", "content": response})
            messages.append({"role": "user", "content": f"Observation: {observation}"})

            self.memory.add("assistant", response)
            self.memory.add("user", f"Observation: {observation}")

        return "I could not complete the task within the step limit."

That's it. The entire agent is:

Format the system prompt with tool descriptions
Send messages to the LLM
Check for "Final Answer:" — if found, return it
Parse "Action:" and "Action Input:" from the response
Execute the tool
Append the observation as a user message
Loop

What Happens at Runtime

When you run:

python main.py --query "What's the weather in Istanbul and what's 15 * 7?"

The conversation looks like this:

[Step 1]
  Action: get_weather
  Input:  {"city": "Istanbul"}
  Result: Weather in Istanbul, Turkey: 22°C, wind 14 km/h

[Step 2]
  Action: calculator
  Input:  {"expression": "15 * 7"}
  Result: 105

Final Answer: The weather in Istanbul is 22°C with 14 km/h wind, and 15 × 7 = 105.

The LLM reasoned: "I need two pieces of information. Let me get the weather first, then do the math, then combine."

The LLM Abstraction

One thing you might have noticed: _call_llm supports multiple backends:

def _call_llm(self, messages: list[dict[str, str]]) -> str:
    if self.llm == "openai":
        from langchain_openai import ChatOpenAI
        model = ChatOpenAI(model="gpt-4o-mini", api_key=settings.openai_api_key)
        return model.invoke(messages).content

    if self.llm == "anthropic":
        from langchain_anthropic import ChatAnthropic
        model = ChatAnthropic(model="claude-3-5-sonnet-20241022", api_key=settings.anthropic_api_key)
        return model.invoke(messages).content

    if self.llm == "ollama":
        from langchain_community.chat_models import ChatOllama
        model = ChatOllama(model="llama3.1:8b", base_url="http://localhost:11434")
        return model.invoke(messages).content

Here's the interesting part: we're using LangChain's LLM wrappers, but not LangChain's agent abstractions. We use LangChain for what it's good at — providing a unified interface to OpenAI, Anthropic, and Ollama — but we keep control of the agent loop ourselves.

Now Let's Compare: LangChain's Built-in Agent

Here's the same functionality using LangChain's create_tool_calling_agent:

from langchain.agents import create_tool_calling_agent, AgentExecutor
from langchain_openai import ChatOpenAI
from langchain.tools import Tool

# Define tools
weather_tool = Tool(name="get_weather", func=get_weather, description="Get current weather for a city.")
calc_tool = Tool(name="calculator", func=calculator, description="Evaluate a safe arithmetic expression.")

# Create the agent
llm = ChatOpenAI(model="gpt-4o-mini")
tools = [weather_tool, calc_tool]

agent = create_tool_calling_agent(llm, tools, prompt)
executor = AgentExecutor(agent=agent, tools=tools, verbose=True)

result = executor.invoke({"input": "What's the weather in Istanbul and what's 15 * 7?"})

That's ~10 lines vs ~170. So why would you ever write the manual version?

The Trade-offs

Here's a side-by-side comparison:

Lines of code: Manual is ~170, LangChain is ~10.
Control over parsing: Manual gives you full visibility — you see every line. LangChain hides it behind AgentExecutor.
Error recovery: Manual lets you nudge the model back on parse failure. LangChain has its own default retry logic.
Memory: Manual uses your own ConversationBufferMemory or VectorMemory. LangChain has its own memory classes.
Debugging: Manual lets you print every step and see every message. LangChain's verbose=True gives you some output.
LLM backend swap: Manual — change one string ("openai" to "ollama"). LangChain — change the LLM class.
Prompt control: Manual — you own the system prompt 100%. LangChain — framework formats it for you.
Learning curve: Manual — read the code, understand every line. LangChain — read docs, trust the abstraction.

When to use the manual approach:

You're learning how agents actually work
You need custom parsing (e.g., your LLM doesn't follow the standard format)
You need custom error recovery (e.g., retry with a different tool on failure)
You want to swap LLMs freely without worrying about LangChain compatibility
You're building a production system where you need full control over the loop

When to use LangChain's AgentExecutor:

You're prototyping and need speed
Your tools are simple and follow standard patterns
You don't need to debug the loop itself
You're already deep in the LangChain ecosystem (using its loaders, retrievers, etc.)

Memory: The Often-Overlooked Component

The manual implementation includes a simple but extensible memory system:

@dataclass
class ConversationBufferMemory:
    """Rolling window of recent conversation messages."""
    max_messages: int = 20
    messages: list[dict[str, str]] = field(default_factory=list)

    def add(self, role: str, content: str) -> None:
        self.messages.append({"role": role, "content": content})
        if len(self.messages) > self.max_messages:
            self.messages = self.messages[-self.max_messages:]

And for long-term semantic memory, there's a ChromaDB-backed option:

class VectorMemory:
    """Semantic long-term memory using ChromaDB."""
    def __init__(self, collection_name="agent_memory", persist_dir="./vector_store"):
        import chromadb
        self.client = chromadb.PersistentClient(path=persist_dir)
        self.collection = self.client.get_or_create_collection(name=collection_name)

    def add(self, text: str, metadata=None, id=None):
        self.collection.add(
            documents=[text],
            metadatas=[metadata or {}],
            ids=[id or str(uuid.uuid4())],
        )

    def query(self, text: str, n_results: int = 5) -> list[str]:
        results = self.collection.query(query_texts=[text], n_results=n_results)
        return results.get("documents", [[]])[0]

This is something LangChain also provides, but again — when you write it yourself, you understand exactly when and how memory is injected into the prompt. With LangChain, it's a config parameter that might not behave the way you expect across different agent types.

Running It Locally with Ollama

One of the biggest advantages of controlling the loop yourself is how easy it is to swap to a local model:

# Install Ollama
ollama pull llama3.1:8b

# Run the agent with a local model — no API costs
python main.py --query "What's the weather in Istanbul?" --llm ollama

That's it. One flag. No LangChain agent type changes, no compatibility concerns. The loop doesn't care which LLM generates the text — it parses the output the same way.

The Full Picture

Here's what the complete kit includes beyond the ReAct loop:

agent.py — the ReAct loop (what we covered above)
tools.py — tool registry with weather, calculator, and web search
memory.py — conversation buffer + vector memory (ChromaDB)
rag_pipeline.py — RAG pipeline using LlamaIndex
fine_tune.py — Unsloth fine-tuning script for local LLMs
ollama_setup.py — local model helper
notebooks/ — step-by-step Jupyter notebooks for each component
guide/ — markdown guides on architecture, LangChain patterns, RAG, fine-tuning, and production deployment

I packaged all of this into a developer kit — it's the code I wish I had when I started building agents. If you want the full source code, notebooks, and guides, you can grab it here

Takeaway

LangChain is excellent for prototyping. But if you're building a production agent system — or if you simply want to understand how agents work under the hood — implementing the ReAct loop yourself is worth every line.

You get:

Full control over parsing, error recovery, and memory
Easy LLM swapping (OpenAI to Anthropic to Ollama with one string)
Zero magic — every behavior is visible in your code
A deeper understanding of what frameworks do for you (and what they hide)

The manual loop is 170 lines. Read it once, and you'll never look at AgentExecutor the same way again.