KoalaCast

A completely free, open-source, privacy-first podcast player for the web.

Calm, distraction-free listening — with optional account-backed cross-device sync.

---

Table of Contents

• Why KoalaCast
• Features
• Quick Start
• Architecture
• Repository Layout
• Development
• Configuration
• Testing
• Documentation
• Contributing
• Security
• License

---

Why KoalaCast

1. 100% free and open source — MIT licensed, no ads, no tracking, no premium tier.
2. Local-first — use the entire app with no account; data lives in your browser's IndexedDB.
3. Optional cross-device sync — an account syncs subscriptions, favorites, playback progress, and listening statistics.
4. Direct publisher audio by default — playback streams straight from the publisher CDN. Self-hosters can opt into an audio relay for browser effects/downloads blocked by publisher CORS.
5. RSS as the source of truth — standard RSS 2.0/Atom plus Podcasting 2.0 tags are preserved.
6. Self-hosting parity — a self-hosted instance has exactly the same capabilities as any official one.

---

Features

Area	Highlights
Discovery & Search	iTunes Top Charts discovery, iTunes/Podcast Index search, multi-select preferred/hidden genres, per-podcast hiding, add any feed by direct RSS URL
Languages	Spoken-language filtering (not just storefront region) for Discover and Search, language + genre search filters, fully translated English/German interface (add a language with one JSON file)
Playback	Web Audio player, Media Session and Remote Playback APIs, playback-speed control, per-podcast controls, live scrubbing with chapter markers, jump-back after a large seek, a sleep timer that counts listening time rather than wall-clock time, a transcript that follows the playhead, timestamp handoff links, listening-time tracking, keyboard shortcuts
Library	Subscriptions with folders, queue plus reusable named queues, smart queues built from saved rules, favorites, timestamp bookmarks, OPML import/export plus an optional auto-updating OPML backup file
Accounts (optional)	Argon2id hashing, Base32 recovery codes, HttpOnly session cookies, Bearer device tokens
Sync	Subscriptions, favorites, playback state, listening sessions, queue, podcast settings, and global settings via monotonic cursor pull/push and idempotent writes; settings merge per field, so two devices editing different preferences do not revert each other
Statistics	Private personal listening analytics plus separately opt-in global aggregates and listener leaderboard
Offline	Downloads with an enforced storage budget, retention policy and parallel-transfer limit; installable as a standalone app; new-episode checks continue in the background where the browser allows it
Customization	Light/dark/system modes, nine palettes with Fjord as default, resizable side rails, per-show playback preferences
Admin	Registration toggle, user suspension, feed-health inspection, manual refresh, system metrics
Backend	Go + chi, SQLite (WAL), SSRF-safe HTTP transport, background feed worker with ETag/304 + backoff
Ops	Multi-stage single-binary Docker image, zero reverse-proxy sidecars, GitHub Actions CI, signed SLSA provenance + SBOM releases

See the full, always-current breakdown in docs/current-status.md.

---

Quick Start (Docker)

# 1. Clone
git clone https://github.com/Shik3i/KoalaCast.git
cd KoalaCast

# 2. Configure — set a strong SESSION_SECRET (32+ chars)
cp .env.example .env

# 3. Launch single Go application binary container on port 3000
docker compose up -d

Open the app at http://localhost:3000.

The single Go application binary (koalacast) serves both the REST API (/api/v1/*) and the static SvelteKit SPA (/*) natively on port 3000 with zero external reverse proxies or sidecars.

Prefer make? See the Makefile targets: make docker-up, make docker-down.

---

Architecture

                                 http://localhost:3000
                                          │
                               ┌──────────▼──────────┐
                               │   Go REST API       │
                               │   (chi router)      │
                               ├─────────────────────┤
                               │ Native Static SPA   │
                               │ Server (/web/build) │
                               └──────────┬──────────┘
                                          │
                        ┌─────────────────┼─────────────────┐
                        │                 │                 │
                ┌───────▼───────┐ ┌───────▼───────┐ ┌───────▼───────┐
                │ SQLite (WAL)  │ │ Feed Worker   │ │ In-Memory RAM │
                │ Database      │ │ Pool          │ │ LRU Cache     │
                └───────────────┘ └───────┬───────┘ └───────────────┘
                                          │
    Web / native audio player ────────────┴────────▶ Direct publisher audio (CDN)

Deep dives live in docs/:

• Architecture & config precedence
• Sync engine protocol
• Feed compatibility & parsing
• Privacy policy & data retention
• Internationalization & language filtering
• Roadmap
• Android architecture

---

Repository Layout

KoalaCast/
├── apps/web/            SvelteKit 5 web client (adapter-static SPA) → apps/web/README.md
├── services/api/        Go REST API, SQLite, workers, SPA server    → services/api/README.md
├── packages/openapi/    OpenAPI 3 contract for the REST API        → packages/openapi/README.md
├── infrastructure/      Minimal multi-stage Alpine Dockerfile       → infrastructure/README.md
├── docs/                Architecture, sync, privacy, feed specs    → docs/README.md
├── testdata/            Sample RSS feeds for tests                 → testdata/README.md
├── docker-compose.yml   Single-command self-host stack
├── Makefile             Developer task runner (make help)
└── .github/workflows/   CI and Docker release pipelines

Every top-level directory has its own README.md describing its contents and conventions.

---

Development

Requirements

• Go 1.25+
• Node.js 24+
• Docker 24+ with Compose (optional, for the container workflow)

Common tasks (make help)

Target	Description
make build	Build the Go API binary and the SvelteKit static SPA bundle
make dev-api	Run the Go API on :3000
make dev-web	Run the SvelteKit dev server on :5173 (proxies /api → :3000)
make test	Go tests with -race, web unit tests, types, docs, translations, and SEO checks
make fmt / make vet	Format Go sources / run go vet
make docker-build / make docker-up / make docker-down	Container workflow
make clean	Remove build artifacts and local databases

Manual dev loop

# Terminal 1 — backend on :3000
cd services/api
SESSION_SECRET=dev-secret-with-at-least-32-characters go run ./cmd/server

# Terminal 2 — frontend on :5173 (Vite proxies /api to :3000)
cd apps/web
npm install
npm run dev

---

Configuration

The backend is configured entirely through environment variables. Copy .env.example to .env and adjust. Key settings:

Variable	Default	Purpose
PORT	3000	Server listen port
SESSION_SECRET	—	Required. 32+ byte secret for session signing
PEPPER_SECRET	empty	Optional HMAC-SHA256 secret key for Argon2id password hashing
DATABASE_PATH	./data/koalacast.db	SQLite database file
KC_REGISTRATION_ENABLED	unset	Hard override for account registration (else DB-controlled)
PODCAST_INDEX_KEY / _SECRET	empty	Optional Podcast Index API creds (iTunes used as fallback)
FEED_WORKER_CONCURRENCY	5	Background feed-refresh workers
FEED_MAX_RESPONSE_BYTES	10485760	Max RSS body size (SSRF/DoS guard)
FEED_MAX_STORED_EPISODES	200	Recent metadata-cache rows retained per podcast; rows referenced by user state are preserved
WEB_PUSH_VAPID_PUBLIC_KEY / _PRIVATE_KEY	empty	Enables server-sent browser notifications; generate once with cd services/api && go run ./cmd/vapid
WEB_PUSH_VAPID_SUBJECT	PUBLIC_BASE_URL	VAPID contact URI (https: or mailto:)
KC_AUDIO_EFFECTS_PROXY_ENABLED	false	Optional relay fallback for CORS-blocked browser effects/downloads; uses the self-hoster's bandwidth

Full precedence rules: docs/architecture/overview.md.

---

Testing

# Backend — unit + integration with the race detector
cd services/api && go test -race ./...

# Frontend — unit tests, types, docs, translations, SEO, production build
cd apps/web && npm test && npm run check && npm run check:docs && npm run check:i18n && npm run check:seo && npm run build

CI runs the same checks plus go vet, gofmt, OpenAPI linting, and Docker builds on every push and PR — see .github/workflows/ci.yml.

---

Documentation

• Users / self-hosters: start with Quick Start and Configuration.
• Contributors: read CONTRIBUTING.md and the per-directory READMEs.
• Specs: browse the docs/ index.

---

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for the workflow, coding standards, and commit conventions, and abide by our Code of Conduct.

---

Security

Found a vulnerability? Please do not open a public issue — follow the disclosure process in SECURITY.md.

---

License

Released under the MIT License — see LICENSE.