https://github.com/linuxmatters/jive-encoder
Drop your podcast .wav into a shiny MP3, AAC or Opus with metadata, cover art, and all đĒŠ
https://github.com/linuxmatters/jive-encoder
aac coverart encoder id3v2 linux macos mp3 opus podcast
Last synced: about 4 hours ago
JSON representation
Drop your podcast .wav into a shiny MP3, AAC or Opus with metadata, cover art, and all đĒŠ
- Host: GitHub
- URL: https://github.com/linuxmatters/jive-encoder
- Owner: linuxmatters
- License: gpl-3.0
- Created: 2025-11-09T08:28:31.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2026-07-04T18:49:35.000Z (2 days ago)
- Last Synced: 2026-07-04T20:13:06.569Z (2 days ago)
- Topics: aac, coverart, encoder, id3v2, linux, macos, mp3, opus, podcast
- Language: Go
- Homepage: https://linuxmatters.sh
- Size: 5.33 MB
- Stars: 8
- Watchers: 0
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
- Support: SUPPORT.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Jive Encoder đī¸
*Formerly known as Jivedrop.*
> Drop your podcast .wav into a shiny MP3, AAC, or Opus with metadata, cover art, and all
## The Groove
Jive Encoder takes your mixed podcast audio (WAV/FLAC) and outputs RSS-ready podcast files with optimised encoding, embedded artwork, and complete metadata. Choose MP3 for universal compatibility, AAC for Apple-recommended quality, or Opus for modern Android and web delivery. One command, distribution-ready output.
### Example Output
### What's Cooking
- đĩ **Multi-format output** via `--format mp3|aac|opus` (default: mp3)
- đ¸ **MP3** CBR 112kbps mono / 192kbps stereo, 44.1kHz, LAME quality 3, 20.5kHz lowpass
- đ **AAC** CBR 64kbps mono / 128kbps stereo, 44.1kHz, `.m4a` (Apple-recommended)
- đ **Opus** VBR ~32kbps mono / ~48kbps stereo, 48kHz, `.opus` (Android/web)
- đˇī¸ **Format-native metadata** - correct tags for each container
- MP3: ID3v2.4 tags with embedded cover art
- AAC: iTunes MP4 atoms with embedded cover art
- Opus: Vorbis comments (text tags; no embedded cover)
- Episode title, number, album, artist, date, comment
- Podcast enclosure stats for duration and bytes
- â **Dual-mode workflow**
- đ **Hugo mode** read metadata from episode markdown
- đī¸ **Standalone mode** specify metadata via flags
- đ **Single binary** Just drop and encode
- đ§ **Linux** (amd64 and aarch64)
- đ **macOS** (x86 and Apple Silicon)
## Usage
### Hugo Mode (Integrated Workflow)
For podcasts using the Hugo static site generator and a theme like [Castanet](https://github.com/mattstratton/castanet), Jive Encoder reads metadata from episode markdown:
**Hugo mode automatically:**
- Reads episode title and number from frontmatter
- Locates cover art from `episode_image` field
- Applies Linux Matters defaults (artist, album, comment)
- Outputs frontmatter-ready values for `podcast_duration` and `podcast_bytes`
- Prompts to update Hugo frontmatter
```bash
# Basic encoding (MP3 by default)
jive-encoder LMP67.flac episode/67.md
# Encode as AAC for Apple-recommended distribution
jive-encoder LMP67.flac episode/67.md --format aac
# Override Hugo defaults
jive-encoder LMP67.flac episode/67.md --artist "Ubuntu Podcast" --comment "https://ubuntupodcast.org"
```
### Standalone Mode (Universal Workflow)
**Standalone mode features:**
- Required flags: `--title`, `--num`, and `--cover`
- Optional metadata: `--artist`, `--album`, `--date`, `--comment`, `--format`
- Smart filename generation: `{artist}-{num}.{ext}` or `episode-{num}.{ext}`
- Album defaults to artist value if not specified
For podcasts without Hugo, specify metadata via flags:
```bash
# Minimal (title, episode number, and cover art required)
jive-encoder audio.flac \
--title "Terminal Full of Sparkles" \
--num 66 \
--cover artwork.png
# Encode as Opus (note: Opus is not accepted by Apple Podcasts)
jive-encoder audio.flac \
--title "Terminal Full of Sparkles" \
--num 66 \
--cover artwork.png \
--format opus
# Full metadata
jive-encoder audio.flac \
--title "Terminal Full of Sparkles" \
--num 66 \
--artist "Linux Matters" \
--album "All Seasons" \
--date "2025-10" \
--comment "https://linuxmatters.sh/66" \
--cover artwork.png \
--format aac
```
## CLI Reference
```
Usage:
Hugo mode:
jive-encoder [flags]
Standalone mode:
jive-encoder --title TEXT --num NUMBER --cover PATH [flags]
Arguments:
[] Path to audio file (WAV, FLAC)
[] Path to episode markdown file (Hugo mode)
Flags:
-h, --help Show context-sensitive help.
--num Episode number, must be a non-negative integer (required in standalone mode)
--title Episode title (required in standalone mode)
--artist Artist name (defaults to 'Linux Matters' in Hugo mode)
--album Album name (defaults to artist value if omitted)
--date Release date (YYYY-MM-DD format)
--comment Comment URL (defaults to 'https://linuxmatters.sh' in Hugo mode)
--cover Cover art path (required in standalone mode)
--output-path Output file or directory path
--format Output format: mp3, aac, or opus (default: mp3)
--stereo Encode as stereo at 192kbps (default: mono at 112kbps)
--version Show version information
```
### Output
- Hugo mode: `LMP{num}.{ext}` (or `{artist}-{num}.{ext}` with `--artist` override)
- Standalone mode: `{artist}-{num}.{ext}` (or `episode-{num}.{ext}` without `--artist`)
Where `{ext}` is `.mp3`, `.m4a`, or `.opus` depending on `--format`.
If `--output-path` names a file, its extension must match `--format`.
### Encoding settings
| Format | Mono | Stereo | Sample rate | Notes |
|--------|------|--------|-------------|-------|
| MP3 (default) | 112 kbps CBR | 192 kbps CBR | 44.1 kHz | LAME quality 3, 20.5 kHz lowpass |
| AAC | 64 kbps CBR | 128 kbps CBR | 44.1 kHz | AAC-LC, `.m4a` (ipod muxer), no lowpass |
| Opus | ~32 kbps VBR | ~48 kbps VBR | 48 kHz | libopus, `.opus`, no lowpass; 48 kHz is Opus's native rate |
### Metadata tags
Tags are written natively by the muxer for each format.
**MP3: ID3v2.4**
- `TIT2`: `{num}: {title}`
- `TALB`: `{album}` (omitted if not provided)
- `TRCK`: `{num}`
- `TPE1`: `{artist}` (omitted if not provided)
- `TDRC`: `{date}` (defaults to current YYYY-MM)
- `COMM`: `{comment}` (omitted if not provided)
- `APIC`: Cover art (PNG, front cover)
**AAC: iTunes MP4 atoms**
Same fields as MP3, written as MP4 atoms. Cover art embedded.
**Opus: Vorbis comments**
Same text fields as MP3. Cover art is not embedded in Opus files.
## Build
Jive Encoder uses [ffmpeg-statigo](https://github.com/linuxmatters/ffmpeg-statigo) for FFmpeg static bindings.
```bash
# Setup or update ffmpeg-statigo submodule and library
just setup
# Build and test
just build # Build binary
just test # Run tests
just test-encoder # Test encoder
```
## Why Jive Encoder?
FFmpeg's CLI can absolutely encode podcast-ready audio with metadata. But getting the incantation right for CBR encoding, mono downmix, format-native tags, embedded artwork, and correct lowpass filtering requires a sprawling command line you'll never remember. Switch from MP3 to AAC and every option changes. Add Hugo frontmatter parsing on top and you're writing a script.
Jive Encoder wraps the fiddly bits into a single binary that speaks Hugo natively. Drop your WAV, point at your episode markdown, pick your format, and get distribution-ready output with duration and byte counts ready to paste back into your frontmatter.