Getting Started

This guide walks you through installation, configuration, and your first content generation.

Prerequisites

AI coding tool with Agent Skills support — Claude Code, Cursor, Windsurf, OpenCode, or similar
ListenHub API Key — create a free account first, then get your API key
curl and jq — usually pre-installed; the AI installs them automatically if missing

npx skills add marswaveai/skills

bunx add-skill marswaveai/skills

After installation, the skill files are added to your project directory automatically.

See Updating Skills for update instructions and AI Agent automation steps.

On first use, the AI detects that no API key is configured and guides you through setup:

The key is saved automatically. You only need to do this once.

You can also set the key manually as an environment variable:

export LISTENHUB_API_KEY="lh_sk_..."

Add this line to ~/.zshrc (macOS) or ~/.bashrc (Linux), then run source ~/.zshrc.

Try one of these prompts to verify everything works:

Example	What happens
`Make a podcast about AI trends`	Generates a podcast episode
`Read this aloud: Hello world`	Converts text to speech audio
`Generate an image: a cat in space`	Creates an AI-generated image
`Transcribe this file: meeting.m4a`	Transcribes audio to text (offline)

The AI handles voice selection, content scripting, and generation automatically. You'll receive a link to listen, watch, or download when it's done.

After generation completes:

Podcast & Speech — the AI displays a link inline by default. To save locally, set output mode to download or both during setup, or say "download audio"
Explainer Video — the AI provides a link inline; download is available on request
Images — displayed inline by default; saved to .listenhub/image-gen/ if output mode is download
Transcripts — available in the episode detail on listenhub.ai

Goal	Prompt
Chinese podcast, quick mode	`Make a podcast about XXX, in Chinese`
English podcast, deep mode	`Make a podcast about XXX, in English, mode: deep`
Explainer video	`Make an explainer video about XXX`
Text-to-speech	`Read this aloud: [your text]`
Image generation	`Generate an image: XXX, 16:9, 2K`

When you don't specify certain parameters, the AI uses sensible defaults:

Parameter	Default
Language	Auto-detected from your input
Podcast mode	Quick + solo (when only a topic is given)
Voice	First available voice for the detected language
Speech mode	FlowSpeech `direct` (reads text as-is)

Learn what each skill can do and how to use it.

Chain skills together for complex workflows.

For more examples and an illustrated walkthrough, see the Way to AGI Workshop Tutorial (Feishu).