Skip to content

INSTALLATION-GUIDE.md

Latest commit

 

History

History
338 lines (243 loc) · 6.46 KB

INSTALLATION-GUIDE.md

File metadata and controls

338 lines (243 loc) · 6.46 KB
Raw

Installation Guide

Complete step-by-step installation instructions for Podcast Ad Cleaner.

Prerequisites

  • Linux operating system (Ubuntu, Arch, Fedora, etc.)
  • Internet connection
  • ~4GB free disk space (for AI models)
  • sudo/root access (for system packages)

Quick Install

git clone https://github.com/adamc199/podcast-ad-cleaner.git
cd podcast-ad-cleaner
chmod +x install.sh
./install.sh

That's it! The install script handles everything automatically.

What Gets Installed

System Packages

The installer will use your system's package manager to install:

  • python3 - Python runtime (v3.8+)
  • python3-pip - Python package manager
  • python3-venv - Virtual environment support
  • ffmpeg - Audio processing
  • curl - HTTP downloads
  • jq - JSON processing
  • yt-dlp - Media downloader

Ollama (AI Server)

  • Downloads and installs Ollama
  • Starts the Ollama service
  • Downloads llama3.2:3b model (~2GB)
  • Configures for local use

Whisper (Speech-to-Text)

  • Creates Python virtual environment at: ~/.podcast-cleaner-env/
  • Installs OpenAI Whisper package
  • Downloads base model (~140MB) on first use

Total Disk Usage

  • System packages: ~500MB
  • Ollama + model: ~2.5GB
  • Whisper + dependencies: ~1.5GB
  • Total: ~4.5GB

Step-by-Step Manual Installation

If you prefer to install manually or the script fails:

1. Install System Dependencies

Ubuntu / Debian / Pop!_OS / Mint:

sudo apt update
sudo apt install -y python3 python3-pip python3-venv ffmpeg curl jq wget

# Install yt-dlp
sudo wget -O /usr/local/bin/yt-dlp https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp
sudo chmod +x /usr/local/bin/yt-dlp

Arch Linux / Manjaro / EndeavourOS:

sudo pacman -S --needed python python-pip ffmpeg curl jq yt-dlp

Fedora / RHEL / CentOS / Rocky:

sudo dnf install -y python3 python3-pip ffmpeg curl jq wget

# Install yt-dlp
sudo wget -O /usr/local/bin/yt-dlp https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp
sudo chmod +x /usr/local/bin/yt-dlp

openSUSE / SUSE:

sudo zypper install -y python3 python3-pip ffmpeg curl jq wget

# Install yt-dlp
sudo wget -O /usr/local/bin/yt-dlp https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp
sudo chmod +x /usr/local/bin/yt-dlp

2. Install Ollama

# Download and install
curl -fsSL https://ollama.ai/install.sh | sh

# Start the server
ollama serve &

# Download the AI model (2GB)
ollama pull llama3.2:3b

# Test it works
ollama run llama3.2:3b "Hello, test!"

3. Install Whisper

# Create virtual environment
python3 -m venv ~/.podcast-cleaner-env

# Activate it
source ~/.podcast-cleaner-env/bin/activate

# Install Whisper
pip install openai-whisper

# Deactivate
deactivate

# Test it works
~/.podcast-cleaner-env/bin/whisper --help

4. Set Up the Script

# Clone repository
git clone https://github.com/adamc199/podcast-ad-cleaner.git
cd podcast-ad-cleaner

# Make script executable
chmod +x podcast-cleaner.sh

# Test it
./podcast-cleaner.sh "test podcast"

5. Add to PATH (Optional)

# Copy to local bin
mkdir -p ~/.local/bin
cp podcast-cleaner.sh ~/.local/bin/podcast-cleaner
chmod +x ~/.local/bin/podcast-cleaner

# Add to PATH (if not already)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Now you can run from anywhere
podcast-cleaner "joe rogan"

Verification

Test each component:

# Check Python
python3 --version  # Should be 3.8+

# Check ffmpeg
ffmpeg -version

# Check yt-dlp
yt-dlp --version

# Check jq
jq --version

# Check Ollama
ollama list  # Should show llama3.2:3b

# Check Whisper
~/.podcast-cleaner-env/bin/whisper --help

# Run full test
./podcast-cleaner.sh "podnews weekly"

Troubleshooting

"Permission denied" during install

Make sure the install script is executable:

chmod +x install.sh
./install.sh

"sudo: command not found"

You need sudo access. Try:

su -
# Then run install commands manually

Ollama won't start

Check if it's already running:

ps aux | grep ollama

# If not, start it
ollama serve &

Whisper installation fails

Try installing system-wide (Arch Linux):

sudo pacman -S python-openai-whisper

Or reinstall in venv:

rm -rf ~/.podcast-cleaner-env
python3 -m venv ~/.podcast-cleaner-env
source ~/.podcast-cleaner-env/bin/activate
pip install --upgrade pip
pip install openai-whisper

"yt-dlp: command not found"

Install manually:

sudo wget -O /usr/local/bin/yt-dlp https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp
sudo chmod +x /usr/local/bin/yt-dlp

# Or use pip
pip install yt-dlp

Whisper model download fails

First run will download models. If it fails:

# Manually download base model
~/.podcast-cleaner-env/bin/python3 -c "import whisper; whisper.load_model('base')"

Uninstallation

To remove everything:

# Remove system packages (careful - may be used by other programs)
# Ubuntu/Debian:
sudo apt remove yt-dlp

# Remove Ollama
sudo rm -rf /usr/local/bin/ollama ~/.ollama

# Remove Whisper environment
rm -rf ~/.podcast-cleaner-env

# Remove the script
rm -rf ~/podcast-ad-cleaner
rm ~/.local/bin/podcast-cleaner 2>/dev/null

# Remove output files
rm -rf ~/cleaned-podcasts

System Requirements

Minimum

  • CPU: 2 cores
  • RAM: 4GB
  • Disk: 5GB free
  • OS: Linux (kernel 4.0+)

Recommended

  • CPU: 4+ cores
  • RAM: 8GB
  • Disk: 10GB free
  • SSD (for faster I/O)

Performance Examples

On a typical modern laptop (4-core CPU, 8GB RAM):

  • 30-min podcast: ~20 minutes processing
  • 60-min podcast: ~40 minutes processing
  • 90-min podcast: ~60 minutes processing

Post-Installation

After installation:

  1. Test the installation:

    ./podcast-cleaner.sh "podnews weekly"

  2. Check output files:

    ls -lh ~/cleaned-podcasts/

  3. Read the documentation:

    cat README.md

  4. Star the repo if it works!

Getting Help

If you encounter issues:

  1. Check this guide's troubleshooting section
  2. Read the main README.md
  3. Search existing GitHub issues
  4. Open a new issue with:
    • Your Linux distribution (cat /etc/os-release)
    • Error messages
    • Steps you've tried

Updates

To update to the latest version:

cd podcast-ad-cleaner
git pull origin main
chmod +x podcast-cleaner.sh install.sh

Note: You don't need to reinstall dependencies unless specified in release notes.