Skip to content

CONFIGURATION.md

Latest commit

 

History

History
162 lines (130 loc) · 4.27 KB

CONFIGURATION.md

File metadata and controls

162 lines (130 loc) · 4.27 KB
Raw

Herzael Configuration Guide

Configuration Hierarchy

Herzael uses a three-tier configuration system:

  1. JSON config file (herzael_config.json, auto-created from config_defaults.py)
  2. Command line arguments (override JSON config)
  3. Runtime state (saved in {pdf}_buffer.json)

Config Modules

AudioConfig

SAMPLE_RATE: int = 48000          # Output audio sample rate
CHANNELS: int = 1                 # Mono audio
FORMAT: str = "s16le"             # Audio format for players
PLAYER_PREFERENCE: tuple = ("paplay", "aplay")  # Try in order
DEFAULT_VOICE: str = "M2"         # Default voice style
VOICE_STYLES: tuple = ("M1", "M2", "F1", "F2")  # Available voices

TTSConfig

MODEL_DIR: str = "models/supertonic"    # TTS model location
TOTAL_STEPS: int = 5                    # Denoising steps (quality)
SPEED: float = 1.0                      # Speech speed multiplier
INTERNAL_SAMPLE_RATE: int = 24000       # Model's native rate
CHUNK_SILENCE: float = 0.3              # Silence between chunks (seconds)

Speed range: 0.9-1.5 recommended

  • < 1.0 = slower, more careful pronunciation
  • 1.0 = natural speed
  • > 1.0 = faster, more rushed

TTS Steps:

  • 5 = Fast mode (real-time capable)
  • 7 = Balanced quality/speed
  • 10 = High quality (slower)

OCRConfig

DPI: int = 200                          # PDF rendering resolution
TESSERACT_PSM: str = "--psm 6"          # Page segmentation mode
MIN_SENTENCE_LENGTH: int = 10           # Filter short extractions
SENTENCE_PATTERN: str = r'(?<=[.!?])\s+'  # Sentence splitting regex

BufferConfig

DEFAULT_MAX_PAGES_AHEAD: int = 3        # OCR buffer size
DEFAULT_SKIP_PAGES: int = 2             # Pages to skip at start
MONITOR_INTERVAL: float = 30.0          # Stats logging interval (seconds)

UIConfig

# Typewriter delays (seconds)
DELAY_SENTENCE_END: float = 0.15        # After . ! ?
DELAY_CLAUSE: float = 0.10              # After , ; :
DELAY_SPACE: float = 0.03               # After space
DELAY_CHAR: float = 0.02                # Default per character

# Keyboard
GETCH_TIMEOUT: int = 100                # Milliseconds
KEYBOARD_POLL_INTERVAL: float = 0.05    # Seconds

# Colors: green (text), yellow+bold (paused), cyan+bold (controls)
# Handled via blessed Terminal library (cross-platform)

# UI text
CONTROLS_TEXT: str = "[SPACE] Pause  |  [LEFT] Previous  |  [RIGHT] Next  |  [Q] Quit"
MAX_TEXT_WIDTH: int = 80

Command Line Usage

Basic

python herzael.py document.pdf

With Voice Selection

python herzael.py document.pdf --voice M1  # Male voice 1
python herzael.py document.pdf --voice F2  # Female voice 2

Speed Control

python herzael.py document.pdf --speed 0.9   # Slower, clearer
python herzael.py document.pdf --speed 1.2   # Faster

Quality Control

python herzael.py document.pdf --tts-steps 10  # High quality
python herzael.py document.pdf --tts-steps 5   # Fast mode

Page Control

python herzael.py document.pdf --skip-pages 5        # Skip first 5 pages
python herzael.py document.pdf --max-pages-ahead 5   # Larger buffer

Combined

python herzael.py book.pdf \
  --voice F1 \
  --speed 1.1 \
  --tts-steps 7 \
  --skip-pages 3 \
  --max-pages-ahead 4

Modifying Defaults

Edit herzael_config.json (auto-created on first run) to change defaults permanently:

{
  "audio": {
    "default_voice": "F1",
    "sample_rate": 48000
  },
  "tts": {
    "total_steps": 7,
    "speed": 1.1
  }
}

Or delete the file to regenerate it from built-in defaults.

Runtime State

Progress is saved to {pdf_name}_buffer.json:

  • Extracts sentences with page numbers
  • Tracks spoken/unspoken status
  • Enables resume functionality

Delete the buffer file to restart from beginning.

Performance Tips

For faster processing:

  • Lower --tts-steps (minimum 5)
  • Increase --speed (max ~1.5)
  • Reduce --max-pages-ahead (saves memory)
  • Lower OCRConfig.DPI in config.py

For better quality:

  • Increase --tts-steps (up to 10)
  • Lower --speed (around 0.9-1.0)
  • Increase OCRConfig.DPI in config.py
  • Increase OCRConfig.MIN_SENTENCE_LENGTH

For smoother playback:

  • Increase --max-pages-ahead (larger buffer)
  • Adjust TTSConfig.CHUNK_SILENCE for pacing