Kinarr

A smart media organizer for home videos with Plex/Jellyfin compatible output. Kinarr automatically monitors folders, classifies media files using AI, and organizes them into a proper folder structure with metadata.

Features

• Folder Monitoring - Watch directories for new media files
• AI Classification - Use Google Gemini AI to automatically identify and classify media
• Smart Matching - Regex patterns and fuzzy matching to identify content
• Jellyfin/Plex Compatible - Generates proper folder structure and NFO metadata files
• Screenshot Generation - Automatic thumbnail and backdrop extraction from videos
• Batch Processing - Process multiple files at once with intelligent grouping
• Directory Browser - Built-in file browser for easy path selection
• Authentication - Optional login protection with username/password
• Multi-language - English and Dutch interface
• Modern UI - Sleek dark theme with synthwave aesthetics

Installation

Docker Compose (Recommended)

Create a docker-compose.yml file:

services:
  kinarr:
    image: ghcr.io/geertgk/kinarr:latest
    container_name: kinarr
    restart: unless-stopped
    environment:
      - TZ=Europe/Amsterdam
      - DEFAULT_SOURCE_DIR=/data/incoming
      - DEFAULT_DEST_DIR=/data/organized
    volumes:
      - ./config:/app/data
      - /path/to/your/media:/data
    ports:
      - 8080:8000

Then run:

docker compose up -d

Open your browser at http://localhost:8080

Updating

docker compose pull
docker compose up -d

Example with Servarr Stack

If you're running Sonarr/Radarr, you can add Kinarr to your existing stack:

  kinarr:
    image: ghcr.io/geertgk/kinarr:latest
    container_name: kinarr
    restart: unless-stopped
    environment:
      - TZ=Europe/Amsterdam
      - DEFAULT_SOURCE_DIR=/data/incoming
      - DEFAULT_DEST_DIR=/data/organized
    volumes:
      - /etc/localtime:/etc/localtime:ro
      - /docker/kinarr/config:/app/data
      - /media:/data
    ports:
      - 8080:8000

Manual Installation (Development)

Click to expand

Requirements

• Python 3.11+
• Node.js 20+
• FFmpeg

Backend Setup

git clone https://github.com/GeertGK/Kinarr.git
cd Kinarr

python -m venv venv
source venv/bin/activate

pip install -r requirements.txt
python -m uvicorn app.main:app --reload

Frontend Setup

cd frontend
npm install
npm run dev

Configuration

All configuration can be done via environment variables or the .env file.

Required Settings

Variable	Description	Default
SOURCE_DIR	Directory to monitor for incoming files	./media/source
DEST_DIR	Directory for organized output	./media/organized

AI Classification (Optional)

Enable smart AI-powered file classification using Google Gemini:

Variable	Description	Default
GEMINI_ENABLED	Enable AI classification	false
GEMINI_API_KEY	Your Gemini API key	-
GEMINI_MODEL	Model to use	gemini-2.0-flash
GEMINI_CONTEXT_PROMPT	Context about your media collection	-

Get your API key at Google AI Studio.

Processing Settings

Variable	Description	Default
FILE_STABILITY_SECONDS	Wait time before processing	3
SUPPORTED_EXTENSIONS	Video extensions to process	.mp4,.mkv,.avi,.mov,.wmv,.m4v,.webm
SCREENSHOT_COUNT	Screenshots per video	3
SCREENSHOT_FORMAT	Screenshot format	jpg
CONFIDENCE_HIGH	Auto-process threshold	0.90
CONFIDENCE_MEDIUM	Notify threshold	0.60

Notifications (Optional)

Variable	Description
SMTP_HOST	SMTP server for email notifications
WEBHOOK_DISCORD	Discord webhook URL
WEBHOOK_SLACK	Slack webhook URL
WEBHOOK_GENERIC	Generic webhook URL

Authentication (Optional)

Protect your Kinarr instance with login authentication:

Variable	Description	Default
AUTH_ENABLED	Enable login protection	false
SECRET_KEY	JWT secret key (change in production!)	change-this-secret-key-in-production
ACCESS_TOKEN_EXPIRE_MINUTES	Token expiration time	10080 (7 days)

When authentication is enabled:

• First visit redirects to setup page to create admin account
• All routes require login
• Configure via Settings > Security

See .env.example for all available options.

Usage

1. Add Library Items

Create TV Shows or Movies in the Library section. Each item can have:

• Custom regex patterns for matching files
• Season organization
• Auto-processing settings

2. Set Up Monitored Folders

Add folders to monitor in the Monitored Folders section:

• Optionally assign to a specific library item
• Enable recursive scanning for subdirectories
• Configure delete-after-processing

3. Process Files

When files are detected:

• High confidence match: Automatically processed
• Medium confidence: Processed with notification
• Low confidence: Added to pending queue for manual review

4. Review Pending Files

In the Pending Files view:

• See AI suggestions with confidence scores
• Approve, edit, or reject suggestions
• Batch process related files together

Output Structure

Kinarr generates Jellyfin/Plex compatible folder structures:

TV Shows/
└── Show Name/
    ├── cover.jpg
    ├── backdrop.webp
    ├── tvshow.nfo
    └── Season 01/
        ├── cover.jpg
        ├── Show Name - S01E01 - Episode Title.mp4
        ├── Show Name - S01E01 - Episode Title.nfo
        └── Show Name - S01E01 - Episode Title-thumb.jpg

Movies/
└── Movie Name (2024)/
    ├── cover.jpg
    ├── backdrop.webp
    ├── Movie Name (2024).mp4
    └── Movie Name (2024).nfo

API

Kinarr exposes a REST API at /api. Key endpoints:

• GET /api/library - List library items
• GET /api/files - List processed files
• GET /api/files/pending - List pending files
• POST /api/monitors/{id}/scan - Trigger folder scan
• GET /api/settings - Get current settings

Tech Stack

Backend:

• FastAPI
• SQLAlchemy (async)
• SQLite
• Google Generative AI (Gemini)
• FFmpeg

Frontend:

• Vue 3 (Composition API)
• Vuetify 3
• Pinia
• Vue I18n
• TypeScript

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE for details.

Acknowledgments

• Inspired by Sonarr and Radarr
• UI design inspired by modern streaming platforms