CDraw - Command-Line AI Music Studio

CDraw is a comprehensive command-line audio workstation that streamlines AI music production from desktop audio capture to final video creation. Built for efficiency and flexibility, CDraw automates your entire audio workflow while providing granular control over each step.

🎵 Features

• Desktop Audio Capture - Record any sound playing on your system
• AI Stem Separation - Separate vocals from instrumentals using Demucs AI
• Professional Audio Enhancement - Multi-stage audio processing and cleanup
• Final Audio Mastering - Commercial-quality mastering with multiple presets
• Music Video Creation - Generate videos from audio and cover art
• Modular Design - Use individual tools or complete workflow
• Complete File Tracking - Full installation manifest for easy removal

🚀 Quick Start

Installation from GitHub

# Clone the repository
git clone https://github.com/CGAlei/CDraw.git
cd CDraw

# Install (requires sudo for /usr/local/bin access)
sudo ./install.sh

# Check installation
cdraw --help

Installation from Downloaded Archive

# Extract downloaded CDraw archive
cd CDraw

# Install (requires sudo for /usr/local/bin access)
sudo ./install.sh

# Check installation
cdraw --help

Basic Usage

# Complete workflow - captures audio, processes it, and creates alpine.mp3 + video
cdraw alpine.mp3

# Process existing audio file
cdraw --input existing_track.wav my_song.mp3

# Skip certain steps
cdraw --skip-capture --skip-video audio_only.wav

🛠️ Individual Commands

Each processing step can be used independently:

# Desktop audio capture
cdraw-capture recorded.wav

# AI stem separation (removes vocals)
cdraw-separate input.wav output_dir/

# Audio enhancement
cdraw-enhance --preset aggressive noisy.wav clean.wav

# Professional mastering
cdraw-master --preset streaming input.wav mastered.wav

# Music video creation
cdraw-video audio.wav cover.jpg music_video.mp4

📋 Requirements

System Dependencies

• PipeWire - Modern Linux audio server (pipewire, pipewire-pulse)
• FFmpeg - Audio/video processing with full codec support
• Python 3.8+ - Runtime for AI processing
• pip - Python package manager

Python Dependencies

• Demucs - AI music source separation (pip install demucs)

Installation Commands by Distribution

Arch Linux

# System packages
sudo pacman -S pipewire pipewire-pulse ffmpeg python python-pip

# Install pipx for isolated Python environments (recommended)
sudo pacman -S python-pipx

# Install Demucs with pipx (recommended method)
pipx install demucs

# Add pipx binaries to PATH if needed
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Alternative: Install Demucs with pip (requires system override on Arch)
pip install demucs --break-system-packages

Ubuntu/Debian

# System packages
sudo apt update
sudo apt install pipewire pipewire-pulse-compat ffmpeg python3 python3-pip

# Install Demucs
pip3 install demucs

Fedora

# System packages
sudo dnf install pipewire pipewire-pulseaudio ffmpeg python3 python3-pip

# Install Demucs
pip3 install demucs

openSUSE

# System packages
sudo zypper install pipewire pipewire-pulseaudio ffmpeg python3 python3-pip

# Install Demucs
pip3 install demucs

🎚️ Workflow Overview

Automated Workflow (cdraw)

1. Capture → Desktop audio recording using PipeWire
2. Separate → AI-powered vocal removal with Demucs
3. Enhance → Audio cleanup and enhancement
4. Manual → Upload enhanced track to Suno AI (user action)
5. Master → Professional mastering of AI-generated result
6. Video → Create music video with cover art

Manual Integration

The workflow includes a manual step where you:

1. Take the enhanced instrumental track
2. Upload it to Suno AI for music generation
3. Download the AI-generated result
4. Provide the path to CDraw for final mastering

⚙️ Configuration

Presets

Enhancement Presets:

• minimal - Light processing for high-quality sources
• balanced - Moderate enhancement (default)
• aggressive - Heavy processing for poor quality audio
• vocal - Optimized for vocal content
• instrumental - Optimized for instrumental content

Mastering Presets:

• streaming - Optimized for streaming platforms (-14 LUFS)
• commercial - Radio/commercial ready (-12 LUFS)
• dynamic - Preserve dynamics (-16 LUFS)
• loud - Maximum loudness (-10 LUFS)

Video Presets:

• youtube - 1920x1080, optimized for YouTube
• instagram - 1080x1080, square format
• tiktok - 1080x1920, vertical format
• twitter - 1280x720, standard HD

Configuration File

Location: ~/.config/cdraw/config.conf

[capture]
sample_rate=44100
format=f32
latency=20ms

[enhancement]
default_preset=balanced

[mastering]
default_preset=streaming
target_lufs=-14

[video]
default_preset=youtube
quality=23

📁 File Locations

/usr/local/bin/
├── cdraw                    # Main workflow script
├── cdraw-capture           # Audio capture
├── cdraw-separate          # Stem separation
├── cdraw-enhance           # Audio enhancement
├── cdraw-master            # Audio mastering
├── cdraw-video             # Video creation
└── cdraw-uninstall         # Complete removal

~/.config/cdraw/
├── config.conf             # User configuration
├── default_cover.jpg       # Default album artwork
├── temp/                   # Temporary processing files
├── logs/                   # Application logs
├── backup/                 # Backup of overwritten files
└── file_manifest.txt       # Installation tracking

🔧 Advanced Usage

Custom Filter Chains

# Custom enhancement filters
cdraw-enhance --filters "highpass=f=100,acompressor=ratio=4,loudnorm=I=-12" input.wav

# Custom mastering chain
cdraw-master --lufs -16 --true-peak -2 --filters "custom_chain" input.wav

Workflow Customization

# Skip capture, use existing file
cdraw --input my_track.wav --skip-separation final.mp3

# Audio-only workflow (no video)
cdraw --skip-video audio_master.wav

# Custom video settings
cdraw-video --preset instagram --quality 20 audio.wav art.jpg video.mp4

Analysis and Testing

# Analyze audio without processing
cdraw-enhance --analyze input.wav
cdraw-master --analyze input.wav

# Dry run - show commands without executing
cdraw --dry-run output.mp3

🗑️ Uninstallation

CDraw tracks all installed files and provides complete removal:

# Remove all CDraw files and directories
cdraw-uninstall

# The uninstaller removes:
# - All executable scripts
# - Configuration directory
# - Default cover image
# - Temporary files
# - Log files
# - The uninstaller itself

🐛 Troubleshooting

Audio Capture Issues

# List available audio sources
cdraw-capture --list-targets

# Test capture with specific target
cdraw-capture --target "your_sink_name" test.wav

# Check PipeWire status
systemctl --user status pipewire
systemctl --user status pipewire-pulse

# Restart PipeWire if needed
systemctl --user restart pipewire pipewire-pulse

Demucs Installation Issues

Arch Linux Specific

# Method 1: pipx (recommended)
sudo pacman -S python-pipx
pipx install demucs

# Method 2: AUR package
yay -S python-demucs
# or
paru -S python-demucs

# Method 3: pip with system override (not recommended)
pip install demucs --break-system-packages

# Check installation
python -c "import demucs; print('Demucs OK')"

Other Distributions

# Ubuntu/Debian
pip3 install demucs
# or
python3 -m pip install demucs

# Check installation
python3 -c "import demucs; print('Demucs OK')"

Permission Issues

# Check audio permissions
groups $USER | grep audio

# Add user to audio group if needed
sudo usermod -a -G audio $USER
# Log out and back in after this

# Check PipeWire permissions
ls -la /run/user/$UID/pulse/

# Ensure PipeWire is running
systemctl --user status pipewire
systemctl --user enable pipewire pipewire-pulse

FFmpeg Issues

# Arch Linux - install additional codecs
sudo pacman -S ffmpeg-libfdk-aac

# Check FFmpeg capabilities
ffmpeg -codecs | grep -E "(mp3|aac|opus)"
ffmpeg -formats | grep -E "(mp4|webm)"

PATH Issues (pipx installations)

# Check if pipx binaries are in PATH
which demucs

# Add to PATH permanently
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Or for zsh users
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

GPU Acceleration (Optional)

# Check NVIDIA GPU support
nvidia-smi

# Install CUDA support for faster Demucs processing
# Arch Linux
sudo pacman -S cuda

# Ubuntu/Debian
sudo apt install nvidia-cuda-toolkit

# Test GPU acceleration
python -c "import torch; print('CUDA available:', torch.cuda.is_available())"

Log Files and Debugging

Check detailed logs in ~/.config/cdraw/logs/ for specific error information:

# View recent logs
tail -f ~/.config/cdraw/logs/main.log
tail -f ~/.config/cdraw/logs/capture.log
tail -f ~/.config/cdraw/logs/enhance.log

# Clear old logs
rm ~/.config/cdraw/logs/*.log

Complete Reinstallation

# Uninstall CDraw completely
cdraw-uninstall

# Remove any remaining configuration
rm -rf ~/.config/cdraw

# Clone and reinstall
git clone https://github.com/CGAlei/CDraw.git
cd CDraw
sudo ./install.sh

📄 License

This project follows the coding principles outlined in claude.md:

• YAGNI (You Aren't Gonna Need It)
• KISS (Keep It Simple, Stupid)
• Single responsibility components
• Clarity over cleverness

🤝 Contributing

CDraw is designed as a personal tool following the specifications in claude.md. The modular architecture makes it easy to extend or modify individual components.

---

CDraw - Transforming your audio workflow into a single, powerful command.