Quacklog

Quacklog is a privacy-focused debugging diary for capturing technical problems as they happen and turning them into structured, searchable notes.

The primary workflow is:

1. Record or upload an audio explanation of a problem.
2. Convert the audio to a Whisper-compatible WAV file.
3. Transcribe the recording locally with whisper.cpp.
4. Send the transcript to a local language model.
5. Generate a structured debugging summary containing:
   • The problem
   • Steps already tried
   • The solution or likely next step
   • Useful tags

Quacklog is designed for developers, support engineers, and technical teams who want to preserve debugging context without sending recordings or transcripts to third-party AI services by default.

Project status: Early development. The audio transcription and summarization pipeline is implemented, while session management, job APIs, and the frontend are still under active development.

Features

Currently implemented

• Audio upload through the backend API
• Upload size limits
• Temporary-file handling for uploaded audio
• Audio conversion through FFmpeg
• Automatic FFmpeg discovery
• Optional FFmpeg download configuration
• Local transcription through whisper.cpp
• Local summarization through:
  • Ollama
  • llama.cpp
• Structured JSON summaries
• SQLite and PostgreSQL database connection support
• Database migrations
• Configurable data directory
• Configurable model and service endpoints
• Configurable CORS origins
• Optional bearer-token configuration for cloud deployments
• Configurable audio, transcript, and summary retention settings
• SvelteKit frontend foundation
• Browser, self-hosted backend, cloud backend, and manual processing modes planned in the UI architecture

Planned or incomplete

The following parts are present in the project structure but are not complete:

• Debugging session CRUD APIs
• Processing job APIs
• Job cancellation and retry handling
• Capabilities endpoint
• Persisting transcription and summary results
• Full debugging-session search API
• Complete frontend workflow
• Browser-local transcription and summarization
• Authentication enforcement
• Production deployment configuration

Architecture

┌──────────────────────┐
│   SvelteKit frontend │
└──────────┬───────────┘
           │ HTTP / JSON / multipart
           ▼
┌──────────────────────┐
│   Actix Web backend  │
└──────────┬───────────┘
           │
           ├── FFmpeg
           │   Converts uploaded audio to 16 kHz mono WAV
           │
           ├── whisper.cpp
           │   Produces a transcript
           │
           ├── Ollama or llama.cpp
           │   Produces a structured debugging summary
           │
           └── SQLite or PostgreSQL
               Stores debugging-session data

Repository layout

.
├── migrations/
│   ├── postgres/
│   └── sqlite/
├── src/
│   ├── auth/
│   ├── config.rs
│   ├── db/
│   ├── error.rs
│   ├── models/
│   ├── routes/
│   ├── services/
│   │   ├── audio.rs
│   │   ├── summarizer.rs
│   │   └── whisper.rs
│   └── main.rs
├── ui/
│   └── SvelteKit frontend
├── Cargo.toml
├── Cargo.lock
├── LICENSE
└── README.md

Requirements

Backend

• Rust toolchain
• FFmpeg
• Git
• A supported database:
  • SQLite
  • PostgreSQL
• whisper.cpp
• A local language-model backend:
  • Ollama, or
  • llama.cpp server

The backend can download and build whisper.cpp when configured to do so. FFmpeg downloads are disabled by default and should only be enabled when you understand and trust the configured download source.

Frontend

• Node.js
• npm, pnpm, yarn, or Bun

The frontend is a SvelteKit application using Svelte 5, Tailwind CSS, and Vite.

Quick start

1. Clone the repository

git clone https://github.com/YOUR_USERNAME/quacklog.git
cd quacklog

Replace YOUR_USERNAME with the GitHub account or organization that will host the repository.

2. Configure the backend

Create a local .env file:

DATABASE_URL=sqlite://./data/quacklog.sqlite

QUACKLOG_DEPLOYMENT_MODE=self-hosted
QUACKLOG_BIND_ADDRESS=127.0.0.1:8080
QUACKLOG_ALLOWED_ORIGINS=http://localhost:5173

QUACKLOG_DATA_DIR=./data

RETAIN_AUDIO=false
RETAIN_TRANSCRIPT=false
RETAIN_SUMMARY=false
JOB_TTL_SECONDS=3600

MAX_AUDIO_UPLOAD_BYTES=262144000

WHISPER_LANGUAGE=en
WHISPER_THREADS=4
WHISPER_TIMEOUT_SECONDS=600

LOCAL_LLM_BACKEND=ollama
OLLAMA_URL=http://127.0.0.1:11434
OLLAMA_MODEL=llama3.2
LLM_TIMEOUT_SECONDS=300

The .env file is ignored by Git. Never commit API tokens, credentials, or private service URLs.

3. Start Ollama

Install Ollama from ollama.com, then pull the configured model:

ollama pull llama3.2
ollama serve

If you prefer llama.cpp, use the following configuration instead:

LOCAL_LLM_BACKEND=llama.cpp
LLAMACPP_URL=http://127.0.0.1:8080
LLAMACPP_MODEL=your-model-name

4. Install or configure FFmpeg

The simplest option is to install FFmpeg using your operating system's package manager.

macOS with Homebrew:

brew install ffmpeg

If FFmpeg is not on your PATH, configure its location:

FFMPEG_BIN=/absolute/path/to/ffmpeg

Automatic FFmpeg downloads are disabled by default. To enable them, configure both values:

ALLOW_FFMPEG_DOWNLOAD=true
FFMPEG_DOWNLOAD_URL=https://trusted.example.com/ffmpeg

Only enable this with a trusted, verified binary source.

5. Run the backend

cargo run

The backend listens on:

http://127.0.0.1:8080

On first startup, Quacklog checks the configured FFmpeg, Whisper, and language-model services. It may download or build the Whisper runtime depending on configuration.

6. Run the frontend

In another terminal:

cd ui
npm install
npm run dev

The frontend development server normally runs at:

http://localhost:5173

API

The currently implemented pipeline endpoints are under /api/v1/pipeline.

Transcribe audio

POST /api/v1/pipeline/transcribe
Content-Type: multipart/form-data

The multipart request must contain an audio field.

Example:

curl \
  -X POST \
  -F "audio=@recording.m4a" \
  http://127.0.0.1:8080/api/v1/pipeline/transcribe

Successful response:

{
	"text": "The application fails when I try to..."
}

The backend:

1. Saves the upload to a temporary file.
2. Converts it to 16 kHz mono WAV with FFmpeg.
3. Runs whisper.cpp.
4. Returns the transcript.

Summarize a transcript

POST /api/v1/pipeline/summarize
Content-Type: application/json

Request:

{
	"transcript": "The application fails when I try to..."
}

Example:

curl \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"transcript":"The application fails when I try to deploy it. I checked the environment variables and rebuilt the container."}' \
  http://127.0.0.1:8080/api/v1/pipeline/summarize

Successful response:

{
	"problem": "The application fails during deployment.",
	"steps_tried": [
		"Checked the environment variables",
		"Rebuilt the container"
	],
	"solution": "Inspect the deployment logs and verify the required runtime configuration.",
	"tags": ["deployment", "environment-variables"]
}

Configuration

Application settings

Variable	Default	Description
QUACKLOG_DEPLOYMENT_MODE	self-hosted	Deployment mode: self-hosted or cloud
DATABASE_URL	required	SQLite or PostgreSQL connection URL
QUACKLOG_BIND_ADDRESS	127.0.0.1:8080	Backend bind address
QUACKLOG_ALLOWED_ORIGINS	empty	Comma-separated CORS origins
QUACKLOG_API_TOKEN	unset	API token for cloud mode
QUACKLOG_DATA_DIR	platform data directory	Location for models and application data
MAX_AUDIO_UPLOAD_BYTES	262144000	Maximum accepted audio upload size in bytes
RETAIN_AUDIO	false	Whether processed audio should be retained
RETAIN_TRANSCRIPT	false	Whether transcripts should be retained
RETAIN_SUMMARY	false	Whether summaries should be retained
JOB_TTL_SECONDS	3600	Intended processing-job retention period

Cloud mode requires QUACKLOG_API_TOKEN.

Whisper settings

Variable	Default	Description
WHISPER_LANGUAGE	en	Whisper language
WHISPER_THREADS	4	Number of Whisper worker threads
WHISPER_TIMEOUT_SECONDS	600	Maximum transcription duration
WHISPER_CPP_REPOSITORY	Whisper.cpp GitHub repository	Whisper source repository
WHISPER_MODEL_URL	Whisper base English model	Model download URL
WHISPER_MODEL_FILENAME	ggml-base.en.bin	Local model filename

FFmpeg settings

Variable	Default	Description
FFMPEG_BIN	auto-detected	Path to an FFmpeg executable
ALLOW_FFMPEG_DOWNLOAD	false	Allow automatic FFmpeg download
FFMPEG_DOWNLOAD_URL	unset	URL used for an automatic FFmpeg download

Local language model settings

Variable	Default	Description
LOCAL_LLM_BACKEND	ollama	ollama or llama.cpp
OLLAMA_URL	http://127.0.0.1:11434	Ollama server URL
OLLAMA_MODEL	llama3.2	Ollama model name
LLAMACPP_URL	http://127.0.0.1:8080	llama.cpp server URL
LLAMACPP_MODEL	unset	Optional llama.cpp model name
LLM_TIMEOUT_SECONDS	300	Maximum summarization duration

Privacy

Quacklog is intended to support private, self-hosted processing, but privacy depends on deployment and configuration.

Important considerations:

• Audio uploads may contain confidential conversations, credentials, customer information, or personal data.
• Set RETAIN_AUDIO=false unless persistent audio storage is explicitly required.
• Review transcript and summary retention settings before production use.
• Self-hosted mode keeps model requests within the configured services, but those services may still log or retain data.
• Cloud mode sends data to the configured remote backend.
• Do not assume that a local model automatically means zero retention.
• Do not expose the backend publicly without authentication, TLS, and appropriate access controls.
• The current pipeline does not yet provide a complete user-facing retention-management workflow.
• The current API does not yet enforce authentication on every route.

Quacklog should not be used with regulated or highly sensitive data until its authentication, authorization, retention, deletion, and audit behavior has been reviewed for that environment.

Database

The project includes SQLite and PostgreSQL migration directories.

SQLite example:

DATABASE_URL=sqlite://./data/quacklog.sqlite

PostgreSQL example:

DATABASE_URL=postgresql://quacklog:password@127.0.0.1:5432/quacklog

The schema is designed around:

• Debugging sessions
• Audio recordings
• Transcriptions
• Structured summaries
• Tags
• Processing jobs
• Full-text search for debugging-session content

The database repositories and higher-level session APIs are still under development.

Development commands

Backend formatting:

cargo fmt --all

Backend checks:

cargo check

Backend tests:

cargo test

Frontend type checking:

cd ui
npm run check

Frontend development server:

cd ui
npm run dev

Frontend production build:

cd ui
npm run build

Security notes

Before deploying Quacklog outside a local machine:

• Bind the service behind a reverse proxy.
• Use HTTPS.
• Add authentication and authorization.
• Restrict CORS origins.
• Keep API tokens out of source control.
• Restrict access to the data directory.
• Review model-server network exposure.
• Set conservative upload limits.
• Decide explicitly whether audio, transcripts, and summaries should be retained.
• Add rate limiting and request logging appropriate to your environment.
• Verify third-party binaries and model downloads.
• Review the licenses of FFmpeg, Whisper models, language models, and other dependencies.

License

The Quacklog source code is provided under the custom license in LICENSE.

This is a source-available, non-commercial license. It is not an OSI-approved open-source license.

You may inspect, copy, modify, and use the code for personal, educational, and internal evaluation purposes, subject to the terms in LICENSE. Commercial use, commercial hosting, resale, sublicensing, and incorporating the code into a commercial product require separate written permission from the copyright holder.

The license protects the copyrightable source code and other covered materials. It cannot prevent independent development of similar ideas or concepts.

Third-party dependencies, models, binaries, and generated assets remain subject to their own licenses.