Skip to content

Config_en

Jump to bottom
SeNS edited this page Sep 23, 2025 · 2 revisions

TinyOPDS Configuration File Documentation

Description

The TinyOPDS configuration file is in XML format and contains all server settings. The file is automatically created on first program launch and can be edited manually or through the graphical interface.

File name: TinyOPDS.config
Location: In the program folder
Format: XML with UTF-8 encoding

Important: When editing the file manually, ensure TinyOPDS is not running, otherwise changes will be overwritten when the program closes.

File Structure

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <userSettings>
    <Portable>
      <TinyOPDS.Properties.Settings>
        <!-- Configuration parameters -->
      </TinyOPDS.Properties.Settings>
    </Portable>
  </userSettings>
</configuration>

Configuration Parameters

Network Settings

ServerPort

  • Type: Integer
  • Default: 8080
  • Description: Port on which the HTTP server operates
  • Example: 8080, 80, 9090

LocalInterfaceIndex

  • Type: Integer
  • Default: 0
  • Description: Network interface index for listening
    • 0 - first found network interface
    • 1, 2, 3... - specific network interface by order
  • Note: Used when system has multiple network cards

UseUPnP

  • Type: Boolean
  • Default: False
  • Description: Use UPnP for automatic router configuration
  • Values: True / False

OpenNATPort

  • Type: Boolean
  • Default: False
  • Description: Automatically open port in NAT router
  • Values: True / False

UseAbsoluteUri

  • Type: Boolean
  • Default: False
  • Description: Use absolute URIs instead of relative in OPDS catalog
  • Values: True / False
  • Note: Enable when working through proxy or if clients incorrectly handle relative links

Library Settings

LibraryPath

  • Type: String
  • Default: Empty
  • Description: Path to books folder
  • Examples:
    • Windows: C:\Books\Library
    • Linux/Mac: /home/user/books

WatchLibrary

  • Type: Boolean
  • Default: False
  • Description: Automatically monitor library changes
  • Values: True / False
  • Note: When enabled, automatically scans new/changed files

ServiceFilesPath

  • Type: String
  • Default: Empty
  • Description: Path to folder with additional files (styles, scripts)
  • Note: Leave empty to use built-in files

Server Settings

ServerName

  • Type: String
  • Default: TinyOPDS
  • Description: Server name displayed in OPDS clients
  • Example: Home Library, My Books

RootPrefix

  • Type: String
  • Default: opds
  • Description: Prefix for OPDS catalog in URL
  • Example: With value opds, catalog is accessible at http://server:8080/opds

HttpPrefix

  • Type: String
  • Default: lib
  • Description: Prefix for web interface in URL
  • Example: With value lib, web interface is accessible at http://server:8080/lib

Display Settings

ItemsPerWebPage

  • Type: Integer
  • Default: 200
  • Description: Number of items per web interface page
  • Recommendations: 50-500 items

ItemsPerOPDSPage

  • Type: Integer
  • Default: 100
  • Description: Number of items per OPDS catalog page
  • Recommendations: 20-200 items (less for mobile devices)

BatchSize

  • Type: Integer
  • Default: 100
  • Description: Batch size when processing books during scanning
  • Recommendations: 50-500 (larger = faster, but uses more memory)

NewBooksPeriod

  • Type: Integer
  • Default: 2
  • Description: Period in weeks for displaying "new" books
  • Example: 2 - books from last 2 weeks are considered new

OPDS Catalog Structure

OPDSStructure

  • Type: String
  • Default: All sections enabled
  • Description: OPDS catalog sections visibility configuration
  • Format: section:state;section:state;...
  • States:
    • 1 - section enabled
    • 0 - section disabled

Available sections:

  • newdate - New books by date
  • newtitle - New books by title
  • authorsindex - Authors index
  • author-details - Author details
  • author-series - Author's books in series
  • author-no-series - Author's books outside series
  • author-alphabetic - Authors alphabetically
  • author-by-date - Authors by date added
  • sequencesindex - Book series index
  • genres - Genres
  • downloads - Downloads/Popular

Example:

<OPDSStructure>newdate:1;newtitle:0;authorsindex:1;genres:1</OPDSStructure>

Enabled: new by date, authors index, genres. Disabled: new by title.

Localization and Sorting

Language

  • Type: String
  • Default: en
  • Description: Interface language
  • Values: en (English), ru (Russian), uk (Ukrainian), etc.

SortOrder

  • Type: Integer
  • Default: 0
  • Description: Sort order for mixed alphabet
  • Values:
    • 0 - Latin first
    • 1 - Cyrillic first

FilterBooksByInterfaceLanguage

  • Type: Boolean
  • Default: False
  • Description: Filter books by interface language
  • Values: True / False
  • Note: When True, shows only books in interface language

UseAuthorsAliases

  • Type: Boolean
  • Default: True
  • Description: Use author aliases
  • Values: True / False

Security and Authorization

UseHTTPAuth

  • Type: Boolean
  • Default: False
  • Description: Use HTTP authorization (Basic Auth)
  • Values: True / False

Credentials

  • Type: String
  • Default: Empty
  • Description: Credentials for HTTP authorization
  • Format: Base64 of username:password or program's special format
  • Note: Configure through GUI for proper encryption

BanClients

  • Type: Boolean
  • Default: False
  • Description: Enable client blocking after failed attempts
  • Values: True / False

WrongAttemptsCount

  • Type: Integer
  • Default: 5
  • Description: Number of failed attempts before blocking client
  • Note: Works only when BanClients=True

RememberClients

  • Type: Boolean
  • Default: False
  • Description: Remember authorized clients
  • Values: True / False

Interface Settings

StartMinimized

  • Type: Boolean
  • Default: False
  • Description: Start program minimized to tray
  • Values: True / False

CloseToTray

  • Type: Boolean
  • Default: False
  • Description: Minimize to tray when closing window
  • Values: True / False

StartWithWindows

  • Type: Boolean
  • Default: False
  • Description: Start with Windows
  • Values: True / False
  • Note: Windows only

OnlyOneInstance

  • Type: Boolean
  • Default: False
  • Description: Allow only one program instance
  • Values: True / False

Caching

CacheImagesInMemory

  • Type: Boolean
  • Default: True
  • Description: Cache book covers in RAM
  • Values: True / False

MaxRAMImageCacheSizeMB

  • Type: Integer
  • Default: 128
  • Description: Maximum image cache size in megabytes
  • Recommendations: 64-512 MB depending on available memory

Logging

LogLevel

  • Type: Integer
  • Default: 0
  • Description: Log detail level
  • Values:
    • 0 - Information (Info)
    • 1 - Warnings (Warning)
    • 2 - Errors (Error)
    • 3 - Authentication

SaveLogToDisk

  • Type: Boolean
  • Default: True
  • Description: Save logs to disk
  • Values: True / False
  • Log file: TinyOPDS.log in program folder

Updates

UpdatesCheck

  • Type: Integer
  • Default: 1
  • Description: Program update check frequency
  • Values:
    • 0 - Never
    • 1 - Once a week
    • 2 - Once a month

LastCheck

  • Type: Date/time
  • Format: MM/dd/yyyy HH:mm:ss
  • Description: Date of last update check
  • Example: 09/22/2025 23:55:38
  • Note: Updates automatically

Example Configurations

Minimal Configuration

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <userSettings>
    <Portable>
      <TinyOPDS.Properties.Settings>
        <LibraryPath>C:\Books</LibraryPath>
        <ServerPort>8080</ServerPort>
      </TinyOPDS.Properties.Settings>
    </Portable>
  </userSettings>
</configuration>

Configuration with Authorization

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <userSettings>
    <Portable>
      <TinyOPDS.Properties.Settings>
        <LibraryPath>/home/user/books</LibraryPath>
        <ServerPort>8080</ServerPort>
        <UseHTTPAuth>True</UseHTTPAuth>
        <Credentials><!-- Configure through GUI --></Credentials>
        <BanClients>True</BanClients>
        <WrongAttemptsCount>3</WrongAttemptsCount>
      </TinyOPDS.Properties.Settings>
    </Portable>
  </userSettings>
</configuration>

Configuration for Large Libraries

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <userSettings>
    <Portable>
      <TinyOPDS.Properties.Settings>
        <LibraryPath>/mnt/nas/books</LibraryPath>
        <ServerPort>80</ServerPort>
        <BatchSize>500</BatchSize>
        <ItemsPerWebPage>500</ItemsPerWebPage>
        <ItemsPerOPDSPage>50</ItemsPerOPDSPage>
        <CacheImagesInMemory>True</CacheImagesInMemory>
        <MaxRAMImageCacheSizeMB>512</MaxRAMImageCacheSizeMB>
        <WatchLibrary>True</WatchLibrary>
      </TinyOPDS.Properties.Settings>
    </Portable>
  </userSettings>
</configuration>

Recommendations

For Home Use

  • Leave most parameters at default
  • Enable CloseToTray and StartMinimized for background operation
  • Use WatchLibrary=True for automatic updates

For Public Access

  • Always enable UseHTTPAuth=True
  • Configure BanClients=True with reasonable WrongAttemptsCount
  • Use non-standard port instead of 8080
  • Reduce ItemsPerOPDSPage for mobile clients

For Large Libraries (100,000+ books)

  • Increase BatchSize to 500-1000
  • Increase MaxRAMImageCacheSizeMB if memory available
  • Disable WatchLibrary and scan on schedule
  • Increase ItemsPerWebPage for easier navigation

Compatibility

  • Configuration file is compatible between TinyOPDS versions
  • GUI and CLI versions use the same configuration file
  • When updating the program, new parameters are added automatically with default values
  • Configuration backup is recommended before updating

Clone this wiki locally