Skip to content

configuration.md

Latest commit

 

History

History
199 lines (145 loc) · 5.21 KB

configuration.md

File metadata and controls

199 lines (145 loc) · 5.21 KB
Raw

⚙️ Configuration Guide

This guide covers all configuration options for the Audiobook Automation System.

📁 Configuration Files

All configuration files are located in the config/ directory:

config/
├── config.yaml                    # Main application configuration
└── config.yaml.example           # Template for main config

🔧 Main Configuration (config.yaml)

Server Settings

server:
  host: "127.0.0.1"
  port: 8080
  debug: false

Database

database:
  path: "db.sqlite"
  backup_enabled: true
  backup_interval_hours: 24

Security

security:
  csrf_enabled: true
  token_length: 32
  rate_limit:
    enabled: true
    max_requests: 10
    window_hours: 1

Metadata Workflow

metadata:
  rate_limit_seconds: 120          # Production: 120s, Testing: 30s
  sources:
    mam:
      enabled: true
      timeout_seconds: 30
    audnex:
      enabled: true
      base_url: "https://api.audnex.us"
      timeout_seconds: 10
    audible:
      enabled: true
      base_url: "https://api.audible.com"
      search_endpoint: "/1.0/catalog/products"
      auth_file: "secrets/audible-auth.json"  # Optional - required only for authenticated Audible lookups

Notifications

notifications:
  discord:
    enabled: false
    webhook_url: ""                # Set in .env as DISCORD_WEBHOOK_URL

  pushover:
    enabled: false
    user_key: ""                   # Set in .env as PUSHOVER_USER_KEY
    api_token: ""                  # Set in .env as PUSHOVER_API_TOKEN

🔐 Environment Variables (.env)

Create a .env file for sensitive configuration:

# Required for webhook authentication
AUTOBRR_TOKEN=your-autobrr-webhook-token

# Notification services (optional)
DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/your/webhook/url
PUSHOVER_USER_KEY=your-pushover-user-key
PUSHOVER_API_TOKEN=your-pushover-api-token
GOTIFY_URL=https://gotify.example.com
GOTIFY_TOKEN=your-gotify-token
NTFY_URL=https://ntfy.sh/your-topic

# MAM API auth (optional, required for MAM metadata lookups)
MAM_ID=your-mam-session-cookie-value

# Authenticated Audible backend
# AUDIBLE_AUTH_FILE=secrets/audible-auth.json
# AUDIBLE_AUTH_FILE_PASSWORD=your-audible-auth-file-password

🔍 MAM API Configuration (Optional)

For full MAM integration with ASIN extraction, set MAM_ID in .env to the value of your MAM mam_id browser cookie. The application uses MAM's JSON API directly and does not log in through the website.

Find the Cookie Value

MAM_ID=your-mam-session-cookie-value

Security note: MAM_ID is a session token. Keep it only in .env, never commit it, and rotate it if it is shared or exposed.

🎧 Authenticated Audible Integration

The Audible backend now uses mkb79/Audible. Configure AUDIBLE_AUTH_FILE and AUDIBLE_AUTH_FILE_PASSWORD only when you want authenticated Audible lookups so the app can decrypt the stored auth JSON and authenticate requests.

The encrypted auth file format used by Authenticator.from_file(...) matches the salt / iv / ciphertext JSON envelope already used by this project.

AUDIBLE_AUTH_FILE_PASSWORD is the decryption password for the auth file. It is not your Audible or Amazon login password.

Installation note: this repo installs mkb79/Audible directly from GitHub because the PyPI release is behind upstream. The supported Python range for the Audible install path is 3.11-3.13.

🎯 Configuration Examples

Development/Testing

metadata:
  rate_limit_seconds: 30           # Faster testing
server:
  debug: true                      # Enable debug mode

Production

metadata:
  rate_limit_seconds: 120          # Respectful API usage
server:
  debug: false                     # Disable debug mode
security:
  rate_limit:
    max_requests: 5                # Stricter rate limiting

✅ Configuration Validation

Test your configuration:

# Test main config
python -c "from src.config import load_config; load_config(); print('✅ Config valid')"

# Test MAM API auth (if configured)
pytest tests/test_mam_api.py -k Integration --no-cov

# Test metadata workflow
python tests/test_metadata_workflow.py

🔧 Troubleshooting

Common Issues

Config file not found:

cp config/config.yaml.example config/config.yaml

MAM API auth fails:

  • Verify MAM_ID in .env is the current mam_id cookie value
  • Log in to MAM in your browser and refresh the cookie value if the API reports authentication failure
  • Make sure the value is not URL-encoded twice or surrounded by quotes

Rate limiting too slow:

  • Adjust metadata.rate_limit_seconds in config.yaml
  • Use 30s for testing, 120s for production

Webhook authentication fails:

  • Verify AUTOBRR_TOKEN in .env file
  • Check autobrr webhook configuration

📋 Configuration Checklist

  • config/config.yaml created and configured
  • .env file created with required tokens
  • MAM_ID set in .env (if using MAM)
  • AUDIBLE_AUTH_FILE and AUDIBLE_AUTH_FILE_PASSWORD set if using authenticated Audible lookups
  • Configuration validated with test scripts
  • Notification services tested (if enabled)
  • Rate limiting configured appropriately