Headless Mode

Run BallonTranslator without GUI for batch processing and automation

Headless Mode

Headless mode allows you to run BallonTranslator without the graphical interface, making it ideal for batch processing, server deployments, and automation workflows.

Basic Usage

Single Execution

Translate one or more directories and exit:

python launch.py --headless --exec_dirs "/path/to/manga1,/path/to/manga2"

Continuous Mode

Stay running and prompt for new directories after each job completes:

python launch.py --headless_continuous

In continuous mode, the program will:

1. Process the initial directories (if provided)
2. Prompt you to enter more directories
3. Repeat until you manually exit (Ctrl+C)

Command-Line Arguments

All headless mode arguments from launch.py:

Argument	Type	Description
--headless	flag	Run without GUI
--headless_continuous	flag	Run without GUI, continuously prompt for new directories
--exec_dirs	string	Comma-separated list of project directories to process
--config_path	string	Path to custom config file (default: config/config.json)
--export-translation-txt	flag	Save translation to txt file after RUN completes
--export-source-txt	flag	Save source text to txt file after RUN completes
--ldpi	float	Logical dots per inch for font rendering (typically 96 or 72)
--debug	flag	Enable debug logging
--proj-dir	string	Open specific project directory on startup (GUI mode)
--reinstall-torch	flag	Force reinstall PyTorch even if already installed
--qt-api	string	Set Qt API (pyqt5/pyqt6/pyside2/pyside6, default: pyqt6)
--requirements	string	Path to requirements file (default: requirements.txt)
--frozen	flag	Skip dependency checks (for packaged installations)
--update	flag	Update repository from git before launching
--nightly	flag	Enable AMD ROCm nightly builds for RDNA GPUs

Configuration

Headless mode loads ALL settings from the config file specified by --config_path (defaults to config/config.json).

Required Configuration

Before running headless mode, configure these settings through the GUI or by editing the config file:

Source and Target Languages

{
  "module": {
    "translate_source": "日本語",
    "translate_target": "English"
  }
}

Automation Modules

{
  "module": {
    "textdetector": "ctd",
    "ocr": "mit48px",
    "inpainter": "lama_large_512px",
    "translator": "google",
    "enable_detect": true,
    "enable_ocr": true,
    "enable_translate": true,
    "enable_inpaint": true
  }
}

Headless-Specific Behavior

When running in headless mode, BallonTranslator automatically:

1. Enables load-on-demand: Models are loaded only when needed

   config.module.load_model_on_demand = True
   

2. Disables cache clearing: Run cache is preserved

   config.module.empty_runcache = False
   

3. Uses offscreen rendering: Qt runs with -platform offscreen

From launch.py:189-191:

if args.headless or args.headless_continuous:
    config.module.load_model_on_demand = True
    config.module.empty_runcache = False

Examples

Example 1: Basic Translation

Translate a manga directory from Japanese to English:

python launch.py --headless --exec_dirs "/home/user/manga/one-piece-ch1"

Example 2: Batch Processing Multiple Directories

python launch.py --headless --exec_dirs "/manga/vol1,/manga/vol2,/manga/vol3"

Example 3: Export Text Files

Translate and export both source and translated text:

python launch.py --headless \
  --exec_dirs "/manga/chapter1" \
  --export-source-txt \
  --export-translation-txt

Example 4: Custom Configuration

Use a different config file for Korean→English translation:

python launch.py --headless \
  --config_path "./configs/korean-to-english.json" \
  --exec_dirs "/manhwa/solo-leveling"

Example 5: Fix Font Rendering Issues

If rendered text appears too small or large, adjust the logical DPI:

# Try 96 DPI (Windows standard)
python launch.py --headless --ldpi 96 --exec_dirs "/manga/chapter1"

# Try 72 DPI (macOS standard)
python launch.py --headless --ldpi 72 --exec_dirs "/manga/chapter1"

Example 6: Debug Mode

Enable detailed logging for troubleshooting:

python launch.py --headless --debug --exec_dirs "/manga/chapter1"

Batch Processing with Shell Scripts

Bash Script (Linux/macOS)

Create batch_translate.sh:

#!/bin/bash

# Array of directories to process
directories=(
    "/manga/series1/chapter1"
    "/manga/series1/chapter2"
    "/manga/series2/chapter1"
)

# Process each directory
for dir in "${directories[@]}"; do
    echo "Processing: $dir"
    python launch.py --headless --exec_dirs "$dir"
    if [ $? -eq 0 ]; then
        echo "✓ Completed: $dir"
    else
        echo "✗ Failed: $dir"
    fi
done

echo "All translations complete!"

Make it executable and run:

chmod +x batch_translate.sh
./batch_translate.sh

PowerShell Script (Windows)

Create batch_translate.ps1:

# Array of directories to process
$directories = @(
    "C:\manga\series1\chapter1",
    "C:\manga\series1\chapter2",
    "C:\manga\series2\chapter1"
)

# Process each directory
foreach ($dir in $directories) {
    Write-Host "Processing: $dir"
    python launch.py --headless --exec_dirs $dir
    if ($LASTEXITCODE -eq 0) {
        Write-Host "✓ Completed: $dir" -ForegroundColor Green
    } else {
        Write-Host "✗ Failed: $dir" -ForegroundColor Red
    }
}

Write-Host "All translations complete!"

Run it:

powershell -ExecutionPolicy Bypass -File batch_translate.ps1

Processing Workflow

When headless mode processes a directory:

1. Load configuration from config file
2. Initialize Qt application in offscreen mode
3. Load fonts from system
4. For each image in the directory:
   • Load image
   • Detect text (if enabled)
   • Run OCR (if enabled)
   • Translate text (if enabled)
   • Inpaint text regions (if enabled)
   • Render translated text
   • Save result
5. Export text files (if requested)
6. Exit (or prompt for next directory in continuous mode)

File Output

Headless mode saves output in the project directory:

project_directory/
├── images/              # Original images
├── result/              # Translated images
├── mask/                # Text masks
├── textlines/           # Detected text regions
└── ballontranslator_proj.json  # Project metadata

Text Export Files

When using --export-source-txt or --export-translation-txt:

project_directory/
├── source_text.txt      # Original text (if --export-source-txt)
└── translation.txt      # Translated text (if --export-translation-txt)

Font Rendering

Logical DPI

The --ldpi parameter controls font rendering size. Different platforms use different default values:

• Windows: 96 DPI
• macOS: 72 DPI
• Linux: Usually 96 DPI

If text appears incorrectly sized in headless mode, try adjusting this value.

Font Loading on Windows

On Windows, headless mode manually loads system fonts because the font database doesn’t initialize properly with offscreen rendering.

From launch.py:257-265:

if sys.platform == 'win32' and (args.headless or args.headless_continuous):
    # font database does not initialise on windows with qpa -offscreen
    from qtpy.QtCore import QStandardPaths
    font_dir_list = QStandardPaths.standardLocations(
        QStandardPaths.StandardLocation.FontsLocation
    )
    for fd in font_dir_list:
        fp_list = find_all_files_recursive(fd, FONT_EXTS)
        for fp in fp_list:
            fnt_idx = QFontDatabase.addApplicationFont(fp)

Performance Optimization

Memory Management

Headless mode automatically enables on-demand model loading to save memory:

config.module.load_model_on_demand = True

This loads models only when needed and can unload them afterwards.

GPU Acceleration

Headless mode fully supports GPU acceleration. Make sure you have:

• CUDA-enabled GPU (NVIDIA)
• Proper PyTorch installation with CUDA support
• Or AMD GPU with ROCm/ZLUDA (see GPU Acceleration)

Parallel Processing

For maximum throughput, process multiple directories in parallel:

# Process 4 directories simultaneously
python launch.py --headless --exec_dirs "/manga/ch1" &
python launch.py --headless --exec_dirs "/manga/ch2" &
python launch.py --headless --exec_dirs "/manga/ch3" &
python launch.py --headless --exec_dirs "/manga/ch4" &
wait

Ensure you have enough GPU memory for parallel processing. Each instance loads its own models.

Troubleshooting

Offscreen Platform Issues

If you see Qt platform plugin errors:

qt.qpa.plugin: Could not find the Qt platform plugin "offscreen"

Ensure you have the complete Qt installation. Try:

pip install --force-reinstall PyQt6

Font Not Found

If specific fonts are missing in headless mode:

1. Verify the font is installed on your system
2. Use --debug to see which fonts are loaded
3. Consider using a more common fallback font in your config

Model Loading Errors

If models fail to load:

1. Ensure all model files are downloaded to data/models/
2. Check that you have sufficient disk space
3. Run with --debug to see detailed error messages

Memory Issues

If you run out of memory:

1. Process directories one at a time instead of using comma-separated lists
2. Reduce image resolution before processing
3. Use lighter models (e.g., lama_mpe instead of lama_large_512px)

Continuous Mode Details

In continuous mode (--headless_continuous):

1. Process initial directories (if provided with --exec_dirs)
2. Display prompt: Enter project directories (comma-separated, or 'exit' to quit):
3. Accept new comma-separated paths
4. Process new batch
5. Repeat from step 2

To exit: type exit or press Ctrl+C

Integration with Other Tools

Docker

Run headless mode in a Docker container:

FROM python:3.11

WORKDIR /app
COPY . /app

RUN python launch.py --frozen

ENTRYPOINT ["python", "launch.py", "--headless"]
CMD ["--exec_dirs", "/manga"]

Cron Jobs (Linux/macOS)

Schedule automatic translations:

# Translate new manga daily at 2 AM
0 2 * * * cd /path/to/BallonsTranslator && python launch.py --headless --exec_dirs "/manga/new"

Task Scheduler (Windows)

Create a scheduled task to run translations automatically.

Next Steps

• Learn about Configuration options
• Set up GPU Acceleration for faster processing
• Create Custom Translators for specialized needs