# Podstream

Podstream is a self-hosted podcast hosting platform for publishing audio shows, managing episodes, generating RSS feeds, and tracking listener analytics.

## Overview

Podstream provides the core tools needed to run a podcast network or independent show without relying on a third-party hosting provider. It stores uploaded audio, validates metadata, publishes standards-compliant podcast RSS feeds, and exposes an admin dashboard for managing shows and episodes.

The platform is designed for teams that need predictable hosting, ownership of subscriber feeds, and simple deployment to cloud or private infrastructure.

## Features

- Multi-show podcast management
- Episode uploads with title, description, artwork, season, and episode metadata
- Automatic podcast RSS feed generation
- Public show pages and episode pages
- Draft, scheduled, and published episode states
- Audio file validation and metadata extraction
- Configurable storage backend for local disk or S3-compatible object storage
- Basic listener analytics by episode, client, country, and referrer
- Admin dashboard for editors and publishers
- Role-based access for owners, editors, and viewers
- Apple Podcasts, Spotify, and generic podcast app compatibility
- Health check endpoint for deployment monitoring

## Install

### Requirements

- Node.js 20 or newer
- PostgreSQL 15 or newer
- Redis 7 or newer
- FFmpeg
- npm or pnpm

### Clone the repository

```bash
git clone https://github.com/example/podstream.git
cd podstream
```

### Install dependencies

```bash
npm install
```

### Configure environment

```bash
cp .env.example .env
```

Update `.env` with your database, storage, and application settings.

### Run database migrations

```bash
npm run db:migrate
```

### Start the development server

```bash
npm run dev
```

The admin dashboard will be available at:

```text
http://localhost:3000/admin
```

## Usage

### Create an admin user

```bash
npm run users:create-admin
```

Follow the prompts to enter an email address, display name, and password.

### Create a show

Log in to the admin dashboard and create a new show with:

- Show title
- Description
- Cover artwork
- Author name
- Category
- Language
- Explicit content setting

After saving, Podstream generates a public RSS feed URL for the show.

### Publish an episode

1. Open the show in the admin dashboard.
2. Select **New Episode**.
3. Upload an audio file.
4. Add episode metadata.
5. Save as draft, schedule for later, or publish immediately.

Published episodes appear in the show RSS feed and public show page.

### Submit a feed to podcast directories

Use the generated RSS feed URL from the show settings page. Submit that URL to podcast directories such as Apple Podcasts, Spotify for Podcasters, Amazon Music, and Pocket Casts.

## Configuration

Podstream is configured with environment variables.

### Application

```env
APP_URL=http://localhost:3000
APP_ENV=development
PORT=3000
SESSION_SECRET=change-me
```

### Database

```env
DATABASE_URL=postgres://podstream:podstream@localhost:5432/podstream
```

### Redis

```env
REDIS_URL=redis://localhost:6379
```

### Storage

Use local storage during development:

```env
STORAGE_DRIVER=local
LOCAL_STORAGE_PATH=./storage/uploads
```

Use S3-compatible storage in production:

```env
STORAGE_DRIVER=s3
S3_ENDPOINT=https://s3.amazonaws.com
S3_BUCKET=podstream-media
S3_REGION=us-east-1
S3_ACCESS_KEY_ID=your-access-key
S3_SECRET_ACCESS_KEY=your-secret-key
S3_PUBLIC_URL=https://cdn.example.com
```

### Audio Processing

```env
FFMPEG_PATH=/usr/bin/ffmpeg
MAX_UPLOAD_SIZE_MB=500
ALLOWED_AUDIO_TYPES=audio/mpeg,audio/mp4,audio/wav,audio/x-wav
```

### Analytics

```env
ANALYTICS_ENABLED=true
ANALYTICS_RETENTION_DAYS=365
ANONYMIZE_IPS=true
```

### Email

```env
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=podstream@example.com
SMTP_PASSWORD=your-password
SMTP_FROM="Podstream <podstream@example.com>"
```

## Production Notes

For production deployments, run Podstream behind a reverse proxy with HTTPS enabled. Configure persistent storage for uploads, enable database backups, and set a strong `SESSION_SECRET`.

Recommended production command:

```bash
npm run build
npm run start
```

## License

MIT