🎬 CineRipR

Intelligent Archive Extraction & Organization for Media Libraries

Features • Quick Start • WebGUI • Documentation • Docker

🎯 What is CineRipR?

CineRipR is a powerful automation tool for managing downloaded media archives. It automatically extracts multi-part archives, organizes TV shows and movies into proper directory structures, and keeps your media library tidy with intelligent cleanup.

Perfect for Plex, Jellyfin, Emby users who download multi-part RAR/ZIP archives!

🎥 The Problem It Solves

Downloaded media often comes as:

Multi-part RAR archives (*.part01.rar, *.r00, *.r01, ...)
Split ZIP files (*.zip.001, *.zip.002, ...)
Nested directory structures with samples, subs, and extras

CineRipR automates everything:

✅ Detects and validates multi-part archives
✅ Extracts with progress tracking
✅ Organizes TV shows into ShowName/Season XX/ structure
✅ Moves processed archives to finished directory
✅ Cleans up old files automatically
✅ Monitors everything via beautiful WebGUI

✨ Features

🚀 Core Functionality

Feature	Description
🗜️ Multi-Part Archives	Full support for RAR5, split ZIPs, and multi-volume archives
📺 Smart TV Show Organization	Automatic detection and organization into `ShowName/Season XX/`
🎬 Movie Organization	Proper naming and structure for movie collections
🎥 TMDB Integration	Auto-fetch metadata and NFO creation for movies and TV episodes (requires API Token)
✅ File Completeness Check	Verifies files are fully downloaded before processing (configurable stability period)
🔄 Real-Time Progress	Live progress bars with color-coded status
🐳 Docker-Ready	Production-tested Docker image with official 7-Zip binary
⚙️ Configurable	WebGUI settings + CLI args + optional TOML config

🌐 WebGUI Dashboard

NEW in v2.0! Modern web-based monitoring interface:

Feature	Description
📊 Real-Time Status	Live processing status and progress tracking
📋 Queue Management	View pending archives and processing queue
💾 System Health	Disk space, CPU, and memory monitoring
📝 Live Logs	Filterable, searchable log viewer
📅 History Timeline	Visual timeline of processed releases
🎨 Dark/Light Mode	Theme toggle with persistent preferences
🎮 Manual Controls	Pause/resume processing on demand
🔊 Toast Notifications	Audio alerts for important events

🛡️ Production-Ready

✅ Docker-optimized with proper permission handling
✅ RAR5 support via official 7-Zip Linux binary
✅ UNC path support for Windows network shares
✅ Automatic retries for network file systems
✅ Demo mode for safe testing
✅ Comprehensive logging with structured output

🚀 Quick Start

Using Docker (Recommended)

# Pull the latest image
docker pull ghcr.io/rokk001/cineripr:latest

# Run with Docker Compose
curl -O https://raw.githubusercontent.com/Rokk001/CineRipR/main/examples/docker-compose.yml
docker-compose up -d

# Access WebGUI at http://localhost:8080

Using pip

# Install
pip install cineripr

# Run with CLI args (no config file needed)
cineripr \
  --download-root /data/downloads \
  --extracted-root /data/extracted \
  --finished-root /data/finished

# Or use config file (optional)
cineripr --config cineripr.toml

🌐 WebGUI

Access the dashboard: Open http://localhost:8080 in your browser

Overview Tab

Real-time statistics: Processed, failed, deleted archives
Current operation: Live progress for active extraction
Control panel: Pause/resume processing

Queue Tab

Processing queue: See what's waiting
Release details: Click any item for detailed view
Status indicators: Color-coded status for each item

System Health Tab

Disk space monitoring: Downloads, extracted, finished paths
System resources: CPU and memory usage
7-Zip version: Installed archive tool version

History Tab

Visual timeline: All processed releases
Duration tracking: See how long each took
Success/failure markers: Quick overview of outcomes

📦 Installation

Docker (Production)

# docker-compose.yml
version: "3.8"
services:
  cineripr:
    image: ghcr.io/rokk001/cineripr:latest
    container_name: cineripr
    ports:
      - "8080:8080"
    volumes:
      - /path/to/downloads:/data/downloads
      - /path/to/extracted:/data/extracted
      - /path/to/finished:/data/finished
      - /path/to/appdata/cineripr:/config  # For settings database
    restart: unless-stopped
    user: "99:100"  # Adjust to your system
    entrypoint: ["/bin/sh", "-c"]
    command: ["umask 000 && exec python -m cineripr.cli --download-root /data/downloads --extracted-root /data/extracted --finished-root /data/finished"]
    
    # Optional: TMDB Integration for Movie Metadata (NFO)
    environment:
      - CINERIPR_TMDB_API_TOKEN=your_tmdb_read_access_token

Python (Development)

# Clone repository
git clone https://github.com/Rokk001/CineRipR.git
cd CineRipR

# Install in development mode
pip install -e .[dev]

# Copy example config
cp examples/cineripr.toml.example cineripr.toml

# Edit configuration
nano cineripr.toml

# Run
cineripr --config cineripr.toml

⚙️ Configuration

Configuration Methods

CineRipR supports multiple configuration methods with priority order:

WebGUI Settings (Highest Priority) - Configure via WebGUI at http://localhost:8080
CLI Arguments - Override settings via command-line
TOML File (Optional) - Legacy configuration file
Defaults - Built-in default values

Docker Deployment (Recommended)

No TOML file required! Configure paths via CLI args, all other settings via WebGUI:

command: ["umask 000 && exec python -m cineripr.cli --download-root /data/downloads --extracted-root /data/extracted --finished-root /data/finished"]
volumes:
  - /path/to/appdata/cineripr:/config  # Settings database stored here

Configure via WebGUI:

Open http://localhost:8080
Go to Settings tab
Configure all settings (scheduling, retention, subfolders, etc.)
Settings are saved automatically in SQLite database

TOML Configuration (Optional)

If you prefer TOML files, create cineripr.toml. Here is a complete reference of all available options:

[paths]
# Directory to scan for archives (can be multiple)
download_roots = ["/data/downloads"]

# Directory where extracted content will be placed
extracted_root = "/data/extracted"

# Directory where original archives are moved after successful extraction
finished_root = "/data/finished"

# Optional: Final destinations for Movies and TV Shows
# If set, recognized content is moved here after extraction/renaming.
# movie_root = "/data/movies"
# tvshow_root = "/data/tvshows"

[options]
# Number of days to keep files in 'finished_root' before deletion
finished_retention_days = 15

# Enable automatic deletion of old files in 'finished_root'
enable_delete = false

# Demo mode: Dry-run only, no files are modified/deleted
demo_mode = false

[subfolders]
# Process 'Sample' directories?
include_sample = false

# Process 'Subs' directories?
include_sub = true

# Process other subdirectories?
include_other = false

[tools]
# Path to 7-Zip executable (auto-detected usually)
# seven_zip = "/usr/bin/7z"

[tmdb]
# TMDB API Token for metadata fetching (Movies & TV)
# api_token = "your_read_access_token_here"

TMDB Integration (Movie & TV Metadata)

To enable automatic NFO (metadata) downloading for movies and TV episodes, add your TMDB API Token to your Docker Compose configuration.

1. Docker Compose (Recommended) Add the CINERIPR_TMDB_API_TOKEN environment variable to your service definition. Here is a complete example:

version: "3.8"
services:
  cineripr:
    image: ghcr.io/rokk001/cineripr:latest
    container_name: cineripr
    restart: unless-stopped
    ports:
      - "8080:8080"
    user: "99:100"
    
    # TMDB API Token
    environment:
      - CINERIPR_TMDB_API_TOKEN=your_tmdb_read_access_token
      
    volumes:
      - /path/to/downloads:/data/downloads
      - /path/to/extracted:/data/extracted
      - /path/to/finished:/data/finished
      - /path/to/movies:/data/movies  # Optional: Final destination for Movies
      - /path/to/tvshows:/data/tvshows # Optional: Final destination for TV Shows
      - /path/to/appdata/cineripr:/config
    command: ["umask 000 && exec python -m cineripr.cli --download-root /data/downloads --extracted-root /data/extracted --finished-root /data/finished --movie-root /data/movies --tvshow-root /data/tvshows"]

2. Local Development (Optional) Only for local testing without Docker. You can add the token to your cineripr.toml (see above) or create a secure local override:

Create cineripr.local.toml (this file is gitignored).
Add your token:

[tmdb]
api_token = "your_token"

CLI Arguments

Set paths via CLI args (required if no TOML file):

cineripr \
  --download-root /data/downloads \
  --extracted-root /data/extracted \
  --finished-root /data/finished \
  --retention-days 30 \
  --enable-delete \
  --webgui-port 9090

Full list: cineripr --help

🐳 Docker

Pre-built Images

# Latest stable release
docker pull ghcr.io/rokk001/cineripr:latest

# Specific version
docker pull ghcr.io/rokk001/cineripr:2.0.0

Building Locally

# Using provided script
./scripts/build-docker.sh 2.0.0

# Or manually
docker build -t cineripr:2.0.0 .

Docker Compose

See examples/docker-compose.yml for production-ready configuration.

Key Features:

✅ Official 7-Zip binary (full RAR5 support)
✅ Automatic permission handling
✅ Health checks
✅ Log rotation
✅ WebGUI on port 8080

📖 Documentation

Quick Links

Document	Description
Architecture Overview	System design and components
Finished Path Logic	How file organization works
Contributing Guide	How to contribute
Docker Permissions	Docker setup guide
Release Notes	All version histories

Examples

Example Config - Full configuration file with comments
Docker Compose - Production-ready Docker setup

Scripts

Build Docker - Build Docker images
Run Tests - Execute test suite
Create Release - Automated release process

🔧 Development

Setup

# Clone and install
git clone https://github.com/Rokk001/CineRipR.git
cd CineRipR
pip install -e .[dev]

# Run tests
./scripts/run-tests.sh --coverage

# Build Docker
./scripts/build-docker.sh

Project Structure

CineRipR/
├── docs/              # Documentation
│   ├── architecture/  # Design docs
│   ├── development/   # Dev guides
│   ├── operations/    # Ops guides
│   └── releases/      # Release notes
├── examples/          # Example configs
├── scripts/           # Build scripts
├── src/cineripr/      # Source code
│   ├── core/         # Core logic
│   ├── extraction/   # Archive handling
│   ├── web/          # WebGUI
│   ├── cli.py        # CLI interface
│   ├── config.py     # Configuration
│   └── progress.py   # Progress tracking
└── tests/            # Test suite
    ├── unit/         # Unit tests
    └── integration/  # Integration tests

Testing

# Run all tests
pytest

# With coverage
pytest --cov=src/cineripr --cov-report=html

# Specific test file
pytest tests/unit/test_config.py

# Verbose output
pytest -v

Code Quality

Linting: ruff check src/
Formatting: ruff format src/
Type Checking: mypy src/

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Quick Contribution Guide

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Run tests (./scripts/run-tests.sh)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Guidelines

Follow existing code style
Add tests for new features
Update documentation
Keep commits atomic and descriptive

📊 Release History

Latest Releases

v2.0.0 - Major restructuring and modernization
v1.0.37 - Critical 7-Zip detection fix
v1.0.36 - Complete WebGUI feature set
v1.0.35 - Major WebGUI overhaul

See CHANGELOG.md for complete history.

🐛 Troubleshooting

Common Issues

Q: Archives fail to extract in Docker

Ensure 7-Zip is properly installed (should auto-detect /usr/local/bin/7z)
Check Docker logs: docker logs cineripr

Q: Permission errors on extracted files

Use user: "99:100" in Docker Compose (adjust to your system)
Use umask 000 in entrypoint for full permissions

Q: WebGUI not accessible

Check port mapping: -p 8080:8080
Verify container is running: docker ps
Check firewall rules

Q: TV shows not organizing correctly

Ensure release names follow standard patterns (Show.Name.S01E01)
Enable debug logging: --debug
Check Finished Path Logic

For more help, see Documentation or open an Issue.

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

🌟 Acknowledgments

7-Zip - Excellent archive tool with RAR5 support
Flask - WebGUI framework
psutil - System monitoring
All contributors and users who provided feedback!

📞 Support & Community

Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: docs/

Made with ❤️ for the media library community

⬆ Back to Top

Name		Name	Last commit message	Last commit date
.continue		.continue
.github		.github
docs		docs
examples		examples
scripts		scripts
src/cineripr		src/cineripr
tests		tests
.dockerignore		.dockerignore
.gitignore		.gitignore
.gitmessage		.gitmessage
CHANGELOG.md		CHANGELOG.md
Dockerfile		Dockerfile
LICENSE		LICENSE
PROJECT_STATUS.md		PROJECT_STATUS.md
PROJECT_STATUS_update.md		PROJECT_STATUS_update.md
README.md		README.md
RELEASE_NOTES.md		RELEASE_NOTES.md
cineripr.toml		cineripr.toml
compile_error.txt		compile_error.txt
compile_error_2.txt		compile_error_2.txt
debug_bytes.py		debug_bytes.py
debug_bytes_v2.py		debug_bytes_v2.py
debug_nfo_enforcement.py		debug_nfo_enforcement.py
pyproject.toml		pyproject.toml
reproduce_dctmp.py		reproduce_dctmp.py
test_err.txt		test_err.txt
test_info_ext.py		test_info_ext.py
test_output.txt		test_output.txt
test_result.txt		test_result.txt
test_tv_tmdb.py		test_tv_tmdb.py

Latest commit

History

Folders and files

Repository files navigation