Hark

Your personal audio briefing system.

Hark turns the things you already follow—newsletters, RSS feeds, PDFs, and keyword alerts—into a personalized daily audio briefing. It isn't just a text-to-speech reader; it uses LLMs to deduplicate overlapping news, synthesize a cohesive script, and deliver it as a private podcast feed you can listen to in your favorite podcast app.

No scrolling. No screen time. Just the signal.

Features

• Universal Ingestion: Pull in content via RSS feeds or a dedicated IMAP email inbox (just forward your favorite newsletters to it).
• AI Synthesis: Overlapping stories are merged into a single narrative, keeping briefings concise and relevant.
• Async Receipts: After a briefing is generated, Hark emails you the full transcript and source links, keeping your listening experience screen-free while providing the receipts.
• Private Podcast Feeds: Each "Show" gets its own secure, tokenized RSS feed. Your audio is completely locked down.
• Self-Hosted: Built on Django, PostgreSQL, and Redis. Your data never leaves your server (aside from the LLM/TTS API calls).

---

🚀 Quickstart (Docker Compose)

The easiest way to run Hark is via Docker. You will need API keys for OpenRouter (for summarization) and ElevenLabs (for text-to-speech).

1. Configure the app

cp config.example.yaml config.yaml

Open config.yaml and add your API keys. Crucially, you must change rss.secure_token to a long, secure random string. The app will refuse to boot if this is left as the default.

2. Start the services

docker compose up -d --build

3. Create an Admin account

docker compose exec web python manage.py createsuperuser

You can now log into the dashboard at http://localhost:8000/admin.

---

🎧 How to Use Hark

Hark is currently managed entirely through the Django Admin dashboard.

1. Create a Show: Go to Shows and add one (e.g., "My Morning Briefing"). Hark will automatically generate a secure token and a private RSS URL for it.
2. Add Sources: Under your Show, add Sources. These can be RSS feed URLs or an Email inbox (if configured in config.yaml).
3. Fetch Content: Go to the Sources list, select your sources, and choose "Fetch selected sources" from the action dropdown. Hark will download the latest articles in the background.
4. Generate a Briefing: Go to the Shows list, select your show, and choose "Generate briefings for selected shows". Hark will grab up to 10 unread items, synthesize a script, generate the audio, and publish it.
5. Listen: Copy your Show's RSS URL and paste it into your podcast app.

---

🔒 Security & Podcast App Compatibility

Because Hark generates private, personalized audio, how you expose Hark to your network matters based on which podcast app you use.

Local Fetchers (e.g., Apple Podcasts, Mimir) These apps download the RSS feed and MP3s directly from your phone.

• Highly Secure: You can run Hark entirely on a private VPN (like Tailscale) without ever exposing it to the public internet.

Cloud Fetchers (e.g., Castro, Overcast, Pocket Casts) These apps send the URL to their backend cloud servers, which crawl the feed and sync the audio back to your phone.

• Requires Public Internet: Cloud servers cannot route into a private VPN. To use these apps, Hark must be exposed to the public internet behind an HTTPS reverse proxy (like Nginx or Cloudflare Tunnels).
• Note: By pasting your URL into these apps, you are granting their servers persistent access to your private feed.

A note on Audio Privacy

By default, Hark ensures that your audio files are strictly locked behind your secure token. If someone guesses the URL to your MP3 file, they will get a 404 error unless they also append ?token=YOUR_TOKEN. (This behavior is controlled by rss.private_audio_urls in config.yaml).

---

🛠️ Advanced: The HTTP API

For power users, Shortcuts, or automation tools (like Tasker/n8n), Hark exposes a JSON API. You authenticate by passing your Master Token either as ?token=YOUR_TOKEN or via an Authorization: Bearer YOUR_TOKEN header.

Method	Path	Purpose
GET	/feeds/<slug>.xml?token=...	Subscribe to a show's RSS feed
POST	/sources/<id>/fetch	Trigger ingestion for a source
POST	/shows/<id>/briefings	Trigger briefing generation
POST	/episodes	Manually create an episode from a URL, PDF, or text
GET	/episodes	List all episodes

Example: Creating a manual episode from a URL

curl -X POST "http://localhost:8000/episodes" \
  -H "Authorization: Bearer YOUR_MASTER_TOKEN" \
  -F "title=Interesting Article" \
  -F "source_url=https://example.com/article" \
  -F "summarize=true"

Running without Docker

If you prefer to run Hark natively, you will need local instances of PostgreSQL, Redis, and optionally ffmpeg (for seamless MP3 concatenation).

pip install -r requirements.txt

export POSTGRES_HOST=localhost POSTGRES_DB=hark POSTGRES_USER=hark POSTGRES_PASSWORD=hark

python manage.py migrate
python manage.py createsuperuser

# Terminal 1 — RQ Worker
python manage.py rqworker default

# Terminal 2 — Web Server
python manage.py runserver 0.0.0.0:8000