Skip to content

Configuration

Jump to bottom
Suresh S edited this page Jul 15, 2025 · 11 revisions

CineSync Configuration Guide

CineSync offers comprehensive configuration options for customizing media organization, automation, and integration features. All settings are configured through the .env file or the web interface.

Configuration Overview

CineSync supports configuration through multiple methods:

  • Environment Variables: Set in .env file for persistent configuration
  • Web Interface: Configure settings through the modern web dashboard
  • Command Line: Override settings for specific operations
  • API: Programmatic configuration management

Core Configuration Variables

Make sure to edit the .env file before running CineSync. Below are the configurable variables organized by category:

Essential Configuration

Core Directories

Variable Description Default Value Required
SOURCE_DIR Source directories containing media files (comma-separated for multiple) /path/to/files ✅
DESTINATION_DIR Destination directory for organized media library /path/to/destination ✅
TMDB_API_KEY TMDb API key for metadata lookup your-api-key ✅

Web Interface Configuration

Variable Description Default Value
CINESYNC_IP IP address for web interface and API 0.0.0.0
CINESYNC_API_PORT Port for API server and WebDAV 8082
CINESYNC_UI_PORT Port for web interface 5173
CINESYNC_AUTH_ENABLED Enable authentication for web interface true
CINESYNC_USERNAME Username for web interface login admin
CINESYNC_PASSWORD Password for web interface login admin

Logging Configuration

Variable Description Default Value
LOG_LEVEL Logging verbosity (DEBUG, INFO, WARNING, ERROR, CRITICAL) INFO

Media Organization Configuration

Layout Options

Variable Description Default Value
CINESYNC_LAYOUT Use simplified Movies/Shows layout false
USE_SOURCE_STRUCTURE Preserve original folder structure false
SHOW_RESOLUTION_STRUCTURE Enable resolution-based subfolders for shows true
MOVIE_RESOLUTION_STRUCTURE Enable resolution-based subfolders for movies true

Content Separation

Variable Description Default Value
ANIME_SEPARATION Separate anime content into dedicated folders true
4K_SEPARATION Separate 4K content into dedicated folders true
KIDS_SEPARATION Separate kids/family content based on ratings false

Custom Folder Names

Variable Description Default Value
CUSTOM_MOVIE_FOLDER Custom folder name for movies CineSync/Movies
CUSTOM_SHOW_FOLDER Custom folder name for TV shows CineSync/Shows
CUSTOM_ANIME_MOVIE_FOLDER Custom folder name for anime movies CineSync/Movies
CUSTOM_ANIME_SHOW_FOLDER Custom folder name for anime shows CineSync/Shows

File Processing

Variable Description Default Value
RENAME_ENABLED Enable file renaming based on metadata false
RENAME_TAGS Tags to include in renamed files Resolutions
ALLOWED_EXTENSIONS File extensions to process .mp4,.mkv,.srt
SKIP_EXTRAS_FOLDER Skip processing extras folder files true
SKIP_ADULT_PATTERNS Skip files matching adult content patterns true

Performance Settings

Variable Description Default Value
MAX_PROCESSES Maximum parallel processing threads 1
SLEEP_TIME Real-time monitoring interval (seconds) 60
SYMLINK_CLEANUP_INTERVAL Cleanup check interval (seconds) 600

Metadata & Database Configuration

Metadata Sources

Variable Description Default Value
TMDB_FOLDER_ID Use TMDb IDs in folder structure false
IMDB_FOLDER_ID Use IMDb IDs in folder structure false
TVDB_FOLDER_ID Use TVDB IDs in folder structure false
ANIME_SCAN Apply specialized anime detection rules false
LANGUAGE Metadata language preference ENGLISH

Collection Management

Variable Description Default Value
MOVIE_COLLECTION_ENABLED Group movies by collections false
RELATIVE_SYMLINK Create relative instead of absolute symlinks false

Database Configuration

Variable Description Default Value
DB_THROTTLE_RATE Throttle rate for database operations (requests per second). Higher values may increase performance but also resource usage. 100
DB_MAX_RETRIES Maximum number of retries for database operations in case of failure. Set to 0 to disable retries. 10
DB_RETRY_DELAY Delay (in seconds) between retry attempts for database operations. 1.0
DB_BATCH_SIZE Batch size for processing records from the database. Increasing this value can improve performance but may use more memory. 1000
DB_MAX_WORKERS Maximum number of parallel workers for database operations. Adjust this value based on your system’s capabilities. 4

Media Server Integration

Plex Configuration

Variable Description Default Value
ENABLE_PLEX_UPDATE Enable automatic Plex library updates false
PLEX_URL Plex Media Server URL your-plex-url
PLEX_TOKEN Plex authentication token your-plex-token

Remote Storage

Variable Description Default Value
RCLONE_MOUNT Enable rclone mount verification false
MOUNT_CHECK_INTERVAL Mount availability check interval (seconds) 30

WebDAV Server Configuration

Server Settings

Variable Description Default Value
CINESYNC_WEBDAV Enable WebDAV server true
WEBDAV_IP WebDAV server IP address 0.0.0.0
WEBDAV_PORT WebDAV server port 8082
WEBDAV_AUTH_ENABLED Enable WebDAV authentication true
WEBDAV_USERNAME WebDAV username admin
WEBDAV_PASSWORD WebDAV password admin

Directory Paths

Source and Destination Directories

  • SOURCE_DIR: Full path to the directory containing input files

    • Example: /mnt/media/incoming or C:\Downloads\Media

  • DESTINATION_DIR: Full path where processed files will be organized

    • Example: /mnt/media/library or D:\Media\Organized

Directory Structure Options

USE_SOURCE_STRUCTURE

  • Type: Boolean
  • Default: false
  • Description: Determines file organization method
  • Options:
    • true: Preserves original folder structure from source
    • false: Organizes files into predefined resolution-based folders

CINESYNC_LAYOUT

  • Type: Boolean
  • Default: false
  • Description: Simplified directory organization
  • Options:
    • true: Separates files into 'Movies' and 'Shows' directories
    • false: Uses more detailed organization method

Example Configurations:

# Preserve original structure
USE_SOURCE_STRUCTURE=true

# Simple Movies/Shows layout
CINESYNC_LAYOUT=true

Logging Configuration

LOG_LEVEL

  • Description: Controls verbosity of application logging
  • Options:
    • DEBUG: Most detailed logging
    • INFO: Standard information messages
    • WARNING: Only warnings and errors
    • ERROR: Critical errors only
    • CRITICAL: Extremely severe errors

Example:

LOG_LEVEL="INFO"  # Recommended for most users

Rclone Mount Configuration

RCLONE_MOUNT

  • Type: Boolean
  • Description: Enables verification of remote storage mount points. Prevents symlink deletion if mount suddenly disconnects.
  • Use Case: Useful for cloud storage or network-mounted drives

MOUNT_CHECK_INTERVAL

  • Type: Integer (seconds)
  • Description: Frequency of checking mount point availability
  • Recommendation: Balance between responsiveness and system load

Example Configuration:

RCLONE_MOUNT=true
MOUNT_CHECK_INTERVAL=30  # Check every 30 seconds

TMDb/IMDB/TVDB Configuration

TMDB_API_KEY

ANIME_SCAN

  • Type: Boolean
  • Description: Enables specialized scanning for anime files
  • Useful for: Anime collections with unique naming conventions

Folder ID and Renaming Options

  • TMDB_FOLDER_ID: Organize folders using TMDb IDs
  • IMDB_FOLDER_ID: Organize folders using IMDb IDs
  • TVDB_FOLDER_ID: Organize folders using TVDB IDs for shows
  • RENAME_ENABLED: Enable file renaming based on metadata

RENAME_TAGS

  • Description: Specify additional tags to include in filename
  • Available Categories:
    1. VideoCodecs: e.g., x264, x265, H.264
    2. AudioCodecs: e.g., AAC, DTS, AC3
    3. AudioAtmos: Dolby Atmos indicator
    4. DynamicRange: HDR, SDR
    5. AudioChannels: 5.1, 7.1
    6. Resolution: 720p, 1080p, 4K
    7. MovieVersions: Director's Cut, Extended
    8. StreamingServices: Netflix, Amazon
    9. Languages: EN, FR, JP, etc ..

Rename Tag Examples:

Basic TMDb ID naming for files

RENAME_TAGS=TMDB

Comprehensive naming with multiple tags

RENAME_TAGS=VideoCodec,DynamicRange,AudioChannels

Full metadata inclusion

RENAME_TAGS=VideoCodec,AudioCodec,AudioAtmos,DynamicRange,AudioChannels,Resolution,Languages,TMDB/IMDB (Use either tmdb or imdb based on folder id)

Rename Tags Detailed Explanation

Example File:

Bird.Box.Barcelona.2023.1080p.NF.WEB-DL.ENGLISH.HINDI.DDP5.1.Atmos.HDR-DV.H.265-GOPI SAHI.mkv

Rename Tag Configurations and Output Examples:

1. Basic Configuration: RENAME_TAGS=TMDB

  • Output: 'Bird Box Barcelona (2023) {tmdb-805320}.mkv'
  • Description: Uses only TMDb ID, stripping most original metadata

2. Resolutions Configuration: RENAME_TAGS=Resolution

  • Output: Bird Box Barcelona (2023) [1080P].mkv
  • Description: Highlights the video resolution

3. Comprehensive Configuration: RENAME_TAGS=VideoCodec,DynamicRange,AudioCodec,AudioChannels,StreamingServices,Languages

  • Output: Bird Box Barcelona (2023) [H265] [HDR] [ATMOS] [DDP5.1] [NF] [EN+HI].mkv
  • Breakdown:
    • H.265: Video Codec
    • HDR-DV: Dynamic Range (HDR with Dolby Vision)
    • DDP5.1: Audio Codec and Channels (Dolby Digital Plus 5.1)
    • NF: Streaming Service (Netflix)
    • [EN+HI]: Languages

4. Language-Focused Configuration: RENAME_TAGS=Languages

  • Output: Bird Box Barcelona (2023) [EN+HI].mkv
  • Description: Emphasizes language and source details

Movie Collection Settings

MOVIE_COLLECTION_ENABLED

  • Type: Boolean
  • Description: Organize movies into collection folders
  • Example: Harry Potter series files in a dedicated folder

System Configuration

RELATIVE_SYMLINK

  • Type: Boolean
  • Description: Create symlinks with relative paths
  • Recommended: true for better portability

MAX_PROCESSES

  • Type: Integer
  • Description: Maximum parallel symlink creation processes
  • Recommendations:
    • Multi-core CPU: Higher values (4-8)
    • Single-core/Low-power: Keep at 1-2

File Handling

Extras Handling

  • SKIP_EXTRAS_FOLDER: Skip processing of extras files
  • EXTRAS_MAX_SIZE_MB: Maximum file size considered as an extra

Content Filtering

  • SKIP_ADULT_PATTERNS: Filter out specific content types using predefined patterns

Performance Tuning

Real-Time Monitoring

  • SLEEP_TIME: Interval between directory change checks

Database Configuration

  • DB_THROTTLE_RATE: Database operation rate limit
  • DB_MAX_RETRIES: Retry attempts for failed operations
  • DB_BATCH_SIZE: Record processing batch size
  • DB_MAX_WORKERS: Parallel database processing threads

Database Configuration Explanation

Key Variables:

DB_THROTTLE_RATE

  • Description: Controls the rate at which database operations are performed, measured in requests per second.
  • Example:
    • If DB_THROTTLE_RATE is set to 1, the script will make one database operation every second.
    • This helps control the load on the database, especially in cases where it's accessed over a network.

DB_BATCH_SIZE

  • Description: Defines the number of records to process at once during each database operation.
  • Example:
    • If DB_BATCH_SIZE is set to 10, the script will process 10 records at once in each database operation.
    • Larger batch sizes increase performance but require more memory.

DB_MAX_RETRIES

  • Description: Defines how many times the script will retry a failed database operation.
  • Example:
    • If DB_MAX_RETRIES is set to 10, the script will attempt to retry a failed operation up to 10 times.
    • If set to 0, no retries will occur.

DB_RETRY_DELAY

  • Description: The time in seconds to wait before retrying a failed database operation.
  • Example:
    • If DB_RETRY_DELAY is set to 1.0, the script will wait 1 second before retrying the operation.

DB_MAX_WORKERS

  • Description: Defines how many parallel workers the script will use to perform database operations.
  • Example:
    • If DB_MAX_WORKERS is set to 4, up to four parallel workers will handle database operations, speeding up processing on systems with multiple CPU cores.

Example Configurations

Processing 1 File per Second:

DB_THROTTLE_RATE = 1  # Limits the processing to one batch per second.
DB_BATCH_SIZE = 1     # Only one file is processed per batch.
  • Outcome:
    • The system will process 1 file every second, with a retry limit of 1 and a 1-second delay between retries.

Processing 10 Files per Second:

DB_THROTTLE_RATE = 1  # Limits the system to one batch per second.
DB_BATCH_SIZE = 10    # Each batch contains 10 files, so 10 files are processed per second.
  • Outcome:
    • The system processes 10 files per second in a single batch, with retries and delays applied as configured.

Fine-Tuning Your System

By adjusting DB_THROTTLE_RATE and DB_BATCH_SIZE, you can:

  • Control the rate at which data is processed.
  • Manage system load on both the database and the script itself.
  • Optimize performance by balancing speed with resource usage.

Adjusting DB_MAX_WORKERS and DB_MAX_RETRIES can help in achieving optimal parallel processing and ensuring that temporary failures are handled effectively.

Pro Tip: Always test configurations in a controlled environment before full deployment!

Content Categorization Examples

Kids Content Separation

When KIDS_SEPARATION=true, CineSync automatically identifies and separates family-friendly content:

Supported Ratings

  • Movies: G, PG (configurable threshold)
  • TV Shows: TV-Y, TV-Y7, TV-G, TV-PG

Example Organization

Destination/
├── Movies/
│   ├── Regular Movies/
│   └── Kids Movies/
└── Shows/
    ├── Regular Shows/
    └── Kids Shows/

4K Content Separation

When 4K_SEPARATION=true, high-quality content is automatically organized:

Movies/
├── 4K/
│   ├── Movie Title (2023) [4K]/
│   └── Another Movie (2024) [HDR]/
└── Regular/
    └── Standard Definition Movies/

Anime Content Organization

With ANIME_SEPARATION=true, anime content gets specialized handling:

Destination/
├── AnimeMovies/
│   ├── Studio Ghibli Collection/
│   └── Individual Anime Movies/
└── AnimeShows/
    ├── Attack on Titan/
    └── Other Anime Series/

Advanced Configuration Examples

High-Performance Setup

# Optimize for large libraries
MAX_PROCESSES=8
DB_THROTTLE_RATE=50.0
DB_BATCH_SIZE=2000
DB_MAX_WORKERS=8

# Enable all automation
AUTO_PROCESSING_ENABLED=true
CINESYNC_LAYOUT=true
4K_SEPARATION=true
ANIME_SEPARATION=true
KIDS_SEPARATION=true

Minimal Resource Setup

# Conservative resource usage
MAX_PROCESSES=1
DB_THROTTLE_RATE=5.0
DB_BATCH_SIZE=100
DB_MAX_WORKERS=2

# Basic organization
CINESYNC_LAYOUT=true
USE_SOURCE_STRUCTURE=false

Media Server Integration

# Plex integration
ENABLE_PLEX_UPDATE=true
PLEX_URL=http://localhost:32400
PLEX_TOKEN=your-actual-token

# WebDAV for streaming
CINESYNC_WEBDAV=true
WEBDAV_AUTH_ENABLED=true
WEBDAV_USERNAME=mediauser
WEBDAV_PASSWORD=secure-password

Configuration Management

Web Interface Configuration

  • Access settings through the web interface at http://localhost:5173
  • Real-time configuration validation and updates
  • Export/import configuration settings
  • Reset to default values when needed

Environment File Management

  • Primary configuration through .env file
  • Support for environment variable overrides
  • Automatic backup of configuration changes
  • Version control friendly configuration format

API Configuration

  • Programmatic configuration management via REST API
  • Real-time configuration updates without restart
  • Bulk configuration operations
  • Configuration validation and error reporting

Next Steps

  1. Installation Guide - Setup and deployment
  2. Web Interface - Web dashboard and management
  3. Docker Volumes - Docker configuration for media servers

Clone this wiki locally