A modern, cross-platform music downloading application supporting multiple streaming services
Ripstream is a comprehensive music downloading application built with modern Python and PyQt6. It provides a user-friendly interface for downloading high-quality music from various streaming services, with support for metadata tagging, artwork embedding, and organized file management.
- Qobuz: Full support with high-quality downloads (up to 24-bit/192kHz)
- Tidal: Artist, album, and track downloads
- Deezer: Complete catalog access
- Spotify: URL parsing and metadata extraction
- Apple Music: URL recognition and processing
- YouTube Music: Video and audio content
- SoundCloud: Track and playlist support
- PyQt6-based modern desktop application
- Dual-view system: Grid and List views for browsing content
- Real-time progress tracking with download statistics
- Responsive design with intuitive navigation
- Dark/Light theme support (configurable)
- Intelligent URL parsing for all supported services
- Automatic service detection from URLs
- Content type recognition (artist, album, track, playlist)
- Batch processing for multiple URLs
- Artist discography browsing with album artwork
- Album track listings with detailed metadata
- Playlist management and organization
- Search functionality across all content types
- Download history with retry capabilities
- Lossless audio support (FLAC, ALAC)
- Multiple quality levels: Low (128kbps) to Hi-Res (24-bit/192kHz)
- Format flexibility: MP3, FLAC, M4A support
- Concurrent downloads with configurable limits
- Comprehensive metadata extraction from streaming services
- Automatic audio file tagging with Mutagen
- Artwork embedding in multiple formats (FLAC, MP3, M4A)
- Custom metadata fields and organization
- ISRC and catalog number support
- Customizable folder structures (Artist/Album/Track)
- Source-specific subdirectories (optional)
- Multi-disc album handling with disc folders
- Safe filename generation with character sanitization
- Duplicate detection and handling
- Service authentication management
- Download behavior customization
- Audio quality preferences per service
- Network settings (SSL verification, rate limiting)
- Advanced options for power users
- Download queue with priority handling
- Automatic retry logic with exponential backoff
- Progress tracking with speed and ETA calculations
- Error handling with detailed logging
- Resume capability for interrupted downloads
- Python 3.12 or higher
- PyQt6 for the GUI interface
- Required Python packages (see requirements.txt)
# Clone the repository
git clone https://github.com/your-username/ripstream.git
cd ripstream
# Install dependencies
pip install -r requirements.txt
# Run the application
python main.py# Install development dependencies
pip install -r requirements-dev.txt
# Install pre-commit hooks
pre-commit install
# Run tests
pytest tests/- Launch the application:
python main.py - Enter a URL: Paste any supported streaming service URL
- Browse content: Switch between Grid and List views
- Download: Click download buttons on desired content
- Monitor progress: Check the Downloads tab for status
# Qobuz
https://open.qobuz.com/artist/123456
https://open.qobuz.com/album/abcdef123456
https://open.qobuz.com/track/789012
# Tidal
https://listen.tidal.com/artist/123456
https://listen.tidal.com/album/123456
https://listen.tidal.com/track/123456
# Spotify
https://open.spotify.com/artist/4Z8W4fKeB5YxbusRsdQVPb
https://open.spotify.com/album/4aawyAB9vmqN3uQ7FjRGTy
https://open.spotify.com/track/4iV5W9uYEdYUVa79Axb7Rh
# And more...
Access preferences through Edit → Preferences to configure:
- Service credentials (email/password or tokens)
- Download locations and folder structures
- Audio quality preferences
- Network settings and rate limits
- Advanced options for metadata and tagging
- Intelligent URL parsing for all streaming services
- Service detection and content type identification
- Metadata extraction from URL parameters
- Base downloader with common functionality
- Service-specific implementations (Qobuz, Tidal, etc.)
- Progress tracking and error handling
- Queue management for batch downloads
- Main window with menu system and navigation
- Discography views (Grid and List)
- Downloads management with statistics
- Preferences dialog with tabbed configuration
- Pydantic-based data models for type safety
- Artist, Album, Track, Playlist representations
- Database integration with SQLAlchemy
- Factory patterns for service-specific data
- Artwork downloading and processing
- Audio file tagging with comprehensive metadata
- Format-specific tagging (FLAC, MP3, M4A)
- Single Responsibility: Each module has a focused purpose
- Type Safety: Full type hinting with Pydantic validation
- Extensibility: Plugin-friendly architecture for new services
- Error Handling: Comprehensive exception handling and logging
- Testing: Extensive test coverage for reliability
# Qobuz settings
qobuz:
email: "your-email@example.com"
password: "your-password"
quality: "lossless" # low, high, lossless, hi_res
# Download settings
downloads:
folder: "/path/to/music"
source_subdirectories: false
disc_subdirectories: true
max_connections: 6
requests_per_minute: 60- Low: ~128 kbps MP3
- High: ~320 kbps MP3
- Lossless: CD quality FLAC (16-bit/44.1kHz)
- Hi-Res: High resolution FLAC (24-bit/96kHz+)
The application includes comprehensive tests:
# Run all tests
pytest tests/
# Run specific test categories
pytest tests/ui/ # UI component tests
pytest tests/downloader/ # Downloader tests
pytest tests/models/ # Model validation tests
pytest tests/metadata/ # Metadata processing tests
# Run with coverage
pytest --cov=src tests/ripstream/
├── main.py # Application entry point
├── src/ripstream/ # Main source code
│ ├── config/ # Configuration management
│ ├── core/ # Core utilities (URL parsing, etc.)
│ ├── downloader/ # Download framework
│ ├── metadata/ # Metadata and tagging
│ ├── models/ # Data models
│ └── ui/ # User interface
├── tests/ # Test suite
├── examples/ # Usage examples
└── images/ # Application assets
- Create service-specific downloader in
src/ripstream/downloader/providers/ - Implement URL patterns in
src/ripstream/core/url_parser.py - Add service configuration in
src/ripstream/config/services.py - Create metadata provider in
src/ripstream/ui/metadata_providers/ - Add comprehensive tests
- Python 3.12+ with modern type hints
- Ruff for linting and formatting
- Pre-commit hooks for code quality
- Pydantic for data validation
- Comprehensive docstrings for all public APIs
Ripstream can be packaged into a standalone executable for easy distribution to end users who don't have Python installed.
# Automated build (recommended)
python build.py
# Or on Windows
build.bat# Using PyInstaller directly
pyinstaller ripstream.spec --cleandist/Ripstream.exe(~55MB): Standalone executabledist/README.txt: User instructions
- Single file: Everything bundled into one executable
- No dependencies: Python runtime and all packages included
- Application icon: Embedded icon for Windows
- Optimized size: Excludes unnecessary modules
- Ready to distribute: Users can run directly
For detailed packaging information, see PACKAGING.md.
We welcome contributions! Please see our contributing guidelines:
- Fork the repository and create a feature branch
- Follow code style guidelines (Ruff formatting)
- Add tests for new functionality
- Update documentation as needed
- Submit a pull request with clear description
# Setup development environment
git clone https://github.com/your-username/ripstream.git
cd ripstream
pip install -r requirements-dev.txt
pre-commit install
# Make changes and test
pytest tests/
ruff check src/ tests/
ruff format src/ tests/
# Submit pull request
git push origin feature-branchThis project is licensed under the MIT License - see the LICENSE file for details.
- streamrip: Inspiration for the original concept
- PyQt6: Excellent GUI framework
- Pydantic: Type-safe data validation
- Mutagen: Audio metadata handling
- aiohttp: Async HTTP client
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Documentation: Wiki
Ripstream - Download music the modern way
Copyright © 2025 ripstream and contributors