Archive safety

PodVault’s job is to keep podcasts, not just fetch them once. These features make sure what you archived is still there, still intact, and still yours.

Episodes are never deleted, just marked

Publishers delist old episodes, and many feeds only show their last N items. When an episode disappears from the feed, PodVault keeps everything it knows about it: title, download status, the saved file and its checksum. Instead of vanishing, the episode is flagged removed from feed · local only on the podcast and episode pages.

If the episode ever comes back to the feed, the flag clears on its own. The Storage page lists every episode kept this way, and the Library’s Archive health card counts them.

Those episodes stay in your podcast app feeds too, so you can keep listening to them.

Integrity checks (SHA-256)

Every freshly downloaded episode gets a SHA-256 checksum at download time. The Integrity check on the Storage page re-hashes every downloaded file and compares it with that baseline. It catches silent corruption that a “does the file exist” check can’t see: a failing disk, a truncated write, a bad edit by another program.

• A file that doesn’t match is flagged corrupt on the Storage page and on its episode page.
• The original checksum and the time it was last verified are kept, so the record still shows when the file was last known to be good.
• Re-download all on the Storage page fetches every corrupt file again.
• The check runs as a background job, and Storage shows the latest result.

Verifying files are still on disk

Files can go missing without PodVault knowing: moved, deleted, or on an external drive that’s unplugged. Verification checks every episode marked as downloaded and marks any whose file is gone as missing.

• Web: Verify all files on the Library page, Verify files on a podcast page, or the missing files row on the Storage page.
• CLI: podvault verify, or podvault verify podcast_name.

The next download picks missing episodes up again, so re-downloading them is:

podvault verify podcast_name
podvault download podcast_name

You can also re-download a single episode from its row on the podcast page or with Re-download on its own page.

Tag completeness

The Storage page’s tag check confirms every MP3 and M4A/M4B/MP4 file has its title, artist and cover art tags. Formats PodVault doesn’t tag (Ogg/Opus, FLAC…) aren’t counted as incomplete.

Database backups

The database holds all your metadata: episodes, download state, checksums, settings and schedules. PodVault backs it up on its own:

• Before syncing feeds, and once a day while the web server is running, at most once every PODVAULT_BACKUP_INTERVAL_HOURS (24).
• The newest PODVAULT_BACKUP_KEEP (7) are kept.
• Backups go to a backups/ folder next to the database (./data/backups in Docker; change it with PODVAULT_BACKUP_DIR), named podvault_data-YYYYmmdd-HHMMSS.db.
• They use SQLite’s online backup API, so they’re consistent even while downloads are running.
• Set PODVAULT_BACKUP_ENABLED=false to turn automatic backups off.

On demand:

podvault backup          # back up now, then list backups
podvault backup --list   # just list them

If the database is ever found corrupted, PodVault recreates it, but first copies the damaged file aside as …-corrupt.db in the same folder. Those copies are never removed by rotation.

Restoring a backup

Stop PodVault, then copy a backup over the database file:

cp backups/podvault_data-20260101-030000.db podvault_data.db

In Docker, stop the container and do the same inside your ./data folder, then start it again.

Tip

Backups live on the same disk as the database. Copy the backups/ folder somewhere else from time to time too.

JSON export

PodVault can export a JSON manifest of your library: every episode it has ever seen, including the ones removed from their feed, with each episode’s checksum and integrity state. It doesn’t depend on PodVault’s own database format, so it’s a portable inventory of your archive.

• One podcast: Export on the podcast page (/podcasts/<name>/export).
• Whole library: Export library on the Storage page (/export).

The export is the inventory, not the audio. Your files already live in an organized folder tree on disk, so exporting doesn’t make a second copy of them.

Files you can use without PodVault

Everything on disk is plain and readable without PodVault: a folder per podcast and per episode, named by your templates, audio with its real extension, complete tags and embedded cover art, and the episode’s original RSS entry saved as episode_metadata.xml.