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

• Description: API key for accessing TMDb services
• Requirement: Must obtain from TMDb Developer Portal

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