🔑 Environment Variables
This page answers which environment variables StoryMatrix consumes, where each value lands, and which names carry secrets.
🧭 Application
Values are never published here; secret-bearing rows identify the variable name only. Pydantic settings use the prefixes declared in src/storymatrix/config/models.py.
| Variable | Consumer | Default | Secret? |
|---|---|---|---|
APP__APP_NAME | src/storymatrix/config/models.py:AppSettings | StoryMatrix | No |
APP__APP_VERSION | src/storymatrix/config/models.py:AppSettings | 0.1.0 | No |
APP__LOG_LEVEL | src/storymatrix/config/models.py:AppSettings | safe-log-level factory | No |
APP__LOG_DIR | src/storymatrix/config/models.py:AppSettings | <repo-root>/logs | No |
APP__OUTPUT_DIR | src/storymatrix/config/models.py:AppSettings | <repo-root>/out | No |
APP__TEMP_DIR | src/storymatrix/config/models.py:AppSettings | <repo-root>/temp | No |
APP__CACHE_DIR | src/storymatrix/config/models.py:AppSettings | <repo-root>/cache | No |
APP__MEDIA_DIR | src/storymatrix/config/models.py:AppSettings | <repo-root>/media | No |
APP__SILENCE_DIR | src/storymatrix/config/models.py:AppSettings | <repo-root>/assets/silence | No |
APP__DATA_DIR | src/storymatrix/config/models.py:AppSettings | <repo-root>/data | No |
APP__DEV_LOCAL_ONLY | src/storymatrix/config/models.py:AppSettings; src/storymatrix/cli/main.py | false | No |
APP__KEEP_TEMP_FILES | src/storymatrix/config/models.py:AppSettings | false | No |
APP__LOW_RESOURCE_MODE | src/storymatrix/config/models.py:AppSettings; src/storymatrix/cli/main.py | false | No |
APP__MAX_TTS_CONCURRENCY | src/storymatrix/config/models.py:AppSettings; src/storymatrix/cli/main.py | 2 | No |
🌐 SERVICES__API__
| Variable | Consumer | Default | Secret? |
|---|---|---|---|
SERVICES__API__HOST | src/storymatrix/config/models.py:APISettings | 0.0.0.0 | No |
SERVICES__API__PORT | src/storymatrix/config/models.py:APISettings | 8000 | No |
SERVICES__API__PUBLIC_BASE_URL | src/storymatrix/config/models.py:APISettings | unset | No |
SERVICES__API__AUTH_ENABLED | src/storymatrix/config/models.py:APISettings | false | No |
SERVICES__API__API_KEY | src/storymatrix/config/models.py:APISettings | unset | Yes |
SERVICES__API__RATE_LIMIT_ENABLED | src/storymatrix/config/models.py:APISettings | false | No |
SERVICES__API__RATE_LIMIT_REQUESTS | src/storymatrix/config/models.py:APISettings | 100 | No |
SERVICES__API__CORS_ENABLED | src/storymatrix/config/models.py:APISettings | true | No |
🖥️ SERVICES__WEB__
| Variable | Consumer | Default | Secret? |
|---|---|---|---|
SERVICES__WEB__HOST | src/storymatrix/config/models.py:WebSettings | 0.0.0.0 | No |
SERVICES__WEB__PORT | src/storymatrix/config/models.py:WebSettings | 8080 | No |
📨 SERVICES__CELERY__
| Variable | Consumer | Default | Secret? |
|---|---|---|---|
SERVICES__CELERY__BROKER_HOST | src/storymatrix/config/models.py:CelerySettings | localhost | No |
SERVICES__CELERY__BROKER_PORT | src/storymatrix/config/models.py:CelerySettings | 6379 | No |
SERVICES__CELERY__RESULT_BACKEND_HOST | src/storymatrix/config/models.py:CelerySettings | localhost | No |
SERVICES__CELERY__RESULT_BACKEND_PORT | src/storymatrix/config/models.py:CelerySettings | 6379 | No |
SERVICES__CELERY__BROKER_URL | src/storymatrix/config/models.py:CelerySettings | redis://localhost:6379/0 | No |
SERVICES__CELERY__RESULT_BACKEND | src/storymatrix/config/models.py:CelerySettings | redis://localhost:6379/0 | No |
SERVICES__CELERY__EAGER_MODE | src/storymatrix/config/models.py:CelerySettings | false | No |
🔎 SERVICES__CHROMA__
| Variable | Consumer | Default | Secret? |
|---|---|---|---|
SERVICES__CHROMA__HOST | src/storymatrix/config/models.py:ChromaConfig | localhost | No |
SERVICES__CHROMA__PORT | src/storymatrix/config/models.py:ChromaConfig | 8000 | No |
SERVICES__CHROMA__COLLECTION_NAME | src/storymatrix/config/models.py:ChromaConfig | story_content | No |
🗄️ SERVICES__DATABASE__
| Variable | Consumer | Default | Secret? |
|---|---|---|---|
SERVICES__DATABASE__URL | src/storymatrix/config/models.py:DatabaseSettings | sqlite:///data/storymatrix.db | No |
SERVICES__DATABASE__USER | src/storymatrix/config/models.py:DatabaseSettings | storymatrix | No |
SERVICES__DATABASE__PASSWORD | src/storymatrix/config/models.py:DatabaseSettings | configured secret | Yes |
SERVICES__DATABASE__HOST | src/storymatrix/config/models.py:DatabaseSettings | localhost | No |
SERVICES__DATABASE__PORT | src/storymatrix/config/models.py:DatabaseSettings | 57757 | No |
SERVICES__DATABASE__DBNAME | src/storymatrix/config/models.py:DatabaseSettings | storymatrix | No |
SERVICES__DATABASE__DATA_DIR | src/storymatrix/config/models.py:DatabaseSettings | data | No |
🎚️ SERVICES__MONTAGE__
| Variable | Consumer | Default | Secret? |
|---|---|---|---|
SERVICES__MONTAGE__TARGET_LOUDNESS_DBFS | src/storymatrix/config/models.py:MontageConfig | -20.0 | No |
SERVICES__MONTAGE__IMPLEMENTATION | src/storymatrix/config/models.py:MontageConfig | ffmpeg | No |
SERVICES__MONTAGE__CROSSFADE_DURATION_MS | src/storymatrix/config/models.py:MontageConfig | 500 | No |
SERVICES__MONTAGE__MUSIC_CROSSFADE_ENABLED | src/storymatrix/config/models.py:MontageConfig | false | No |
SERVICES__MONTAGE__MUSIC_CROSSFADE_MS | src/storymatrix/config/models.py:MontageConfig | 1000 | No |
🗣️ SERVICES__PIPER__
| Variable | Consumer | Default | Secret? |
|---|---|---|---|
SERVICES__PIPER__PIPER_BINARY | src/storymatrix/config/models.py:PiperConfig | piper | No |
SERVICES__PIPER__VOICES_DIR | src/storymatrix/config/models.py:PiperConfig | ./models/voices/piper | No |
SERVICES__PIPER__MODELS_DIR | src/storymatrix/config/models.py:PiperConfig | ./models/voices/piper | No |
SERVICES__PIPER__DEFAULT_VOICE | src/storymatrix/config/models.py:PiperConfig | en_US-ljspeech-high | No |
SERVICES__PIPER__QUALITY | src/storymatrix/config/models.py:PiperConfig | high | No |
SERVICES__PIPER__SPEED | src/storymatrix/config/models.py:PiperConfig | 1.0 | No |
SERVICES__PIPER__NOISE_SCALE | src/storymatrix/config/models.py:PiperConfig | 0.667 | No |
SERVICES__PIPER__NOISE_W | src/storymatrix/config/models.py:PiperConfig | 0.8 | No |
SERVICES__PIPER__TIMEOUT_SECONDS | src/storymatrix/config/models.py:PiperConfig | 120 | No |
SERVICES__PIPER__ENABLE_GPU | src/storymatrix/config/models.py:PiperConfig | false | No |
SERVICES__PIPER__AUTO_DOWNLOAD | src/storymatrix/config/models.py:PiperConfig | false | No |
📁 SERVICES__LOCAL_ASSETS__
| Variable | Consumer | Default | Secret? |
|---|---|---|---|
SERVICES__LOCAL_ASSETS__MIN_SIMILARITY_SCORE | src/storymatrix/config/models.py:LocalAssetsConfig; src/storymatrix/cli/main.py | 0.35 | No |
SERVICES__LOCAL_ASSETS__SFX_LIBRARY_PATH | src/storymatrix/config/models.py:LocalAssetsConfig | <repo-root>/assets/sfx | No |
SERVICES__LOCAL_ASSETS__MUSIC_LIBRARY_PATH | src/storymatrix/config/models.py:LocalAssetsConfig | <repo-root>/assets/music | No |
SERVICES__LOCAL_ASSETS__VOICE_DATA_PATH | src/storymatrix/config/models.py:LocalAssetsConfig | <repo-root>/models/voices | No |
🧠 SERVICES__SENTENCE_TRANSFORMER__
| Variable | Consumer | Default | Secret? |
|---|---|---|---|
SERVICES__SENTENCE_TRANSFORMER__MODEL_NAME | src/storymatrix/config/models.py:SentenceTransformerConfig | all-MiniLM-L6-v2 | No |
SERVICES__SENTENCE_TRANSFORMER__CACHE_FOLDER | src/storymatrix/config/models.py:SentenceTransformerConfig | unset | No |
🧪 SERVICES__LLM__
| Variable | Consumer | Default | Secret? |
|---|---|---|---|
SERVICES__LLM__OPEN_ROUTER__TIMEOUT | src/storymatrix/config/models.py:OpenRouterServiceConfig; src/storymatrix/config/config.py | 30 | No |
This is a test-facing compatibility namespace; canonical OpenRouter provider variables use PROVIDERS__OPENROUTER__.
🔐 Provider credentials and settings
ElevenLabs
| Variable | Consumer | Default | Secret? |
|---|---|---|---|
PROVIDERS__ELEVENLABS__API_KEY | src/storymatrix/config/models.py:ElevenLabsConfig | unset | Yes |
PROVIDERS__ELEVENLABS__DEFAULT_VOICE | src/storymatrix/config/models.py:ElevenLabsConfig | 21m00Tcm4TlvDq8ikWAM | No |
PROVIDERS__ELEVENLABS__MODEL_STRATEGY | src/storymatrix/config/models.py:ElevenLabsConfig | eleven_multilingual_v2 | No |
PROVIDERS__ELEVENLABS__MODEL_ID | src/storymatrix/config/models.py:ElevenLabsConfig | unset | No |
PROVIDERS__ELEVENLABS__STABILITY | src/storymatrix/config/models.py:ElevenLabsConfig | 0.5 | No |
PROVIDERS__ELEVENLABS__SIMILARITY_BOOST | src/storymatrix/config/models.py:ElevenLabsConfig | 0.8 | No |
PROVIDERS__ELEVENLABS__STYLE | src/storymatrix/config/models.py:ElevenLabsConfig | 0.0 | No |
PROVIDERS__ELEVENLABS__USE_SPEAKER_BOOST | src/storymatrix/config/models.py:ElevenLabsConfig | true | No |
PROVIDERS__ELEVENLABS__SPEED | src/storymatrix/config/models.py:ElevenLabsConfig | 1.0 | No |
PROVIDERS__ELEVENLABS__V3_AUDIO_TAGS_ENABLED | src/storymatrix/config/models.py:ElevenLabsConfig | true | No |
PROVIDERS__ELEVENLABS__V3_AUTO_ENHANCE_PROMPTS | src/storymatrix/config/models.py:ElevenLabsConfig | true | No |
PROVIDERS__ELEVENLABS__OUTPUT_FORMAT | src/storymatrix/config/models.py:ElevenLabsConfig | mp3_44100_128 | No |
PROVIDERS__ELEVENLABS__SFX_ENABLED | src/storymatrix/config/models.py:ElevenLabsConfig | true | No |
PROVIDERS__ELEVENLABS__SFX_DURATION_SECONDS | src/storymatrix/config/models.py:ElevenLabsConfig | 10 | No |
PROVIDERS__ELEVENLABS__SFX_PROMPT_INFLUENCE | src/storymatrix/config/models.py:ElevenLabsConfig | 0.3 | No |
PROVIDERS__ELEVENLABS__PRONUNCIATION_DICTIONARY_IDS | src/storymatrix/config/models.py:ElevenLabsConfig | [] | No |
PROVIDERS__ELEVENLABS__OPTIMIZE_STREAMING_LATENCY | src/storymatrix/config/models.py:ElevenLabsConfig | 0 | No |
PROVIDERS__ELEVENLABS__APPLY_TEXT_NORMALIZATION | src/storymatrix/config/models.py:ElevenLabsConfig | auto | No |
PROVIDERS__ELEVENLABS__MAX_RETRIES | src/storymatrix/config/models.py:ElevenLabsConfig | 3 | No |
PROVIDERS__ELEVENLABS__TIMEOUT_SECONDS | src/storymatrix/config/models.py:ElevenLabsConfig | 60 | No |
Freesound
| Variable | Consumer | Default | Secret? |
|---|---|---|---|
PROVIDERS__FREESOUND__API_KEY | src/storymatrix/config/models.py:FreesoundConfig | unset | Yes |
OpenRouter
| Variable | Consumer | Default | Secret? |
|---|---|---|---|
PROVIDERS__OPENROUTER__API_KEY | src/storymatrix/config/models.py:OpenRouterConfig | unset | Yes |
PROVIDERS__OPENROUTER__BASE_URL | src/storymatrix/config/models.py:OpenRouterConfig | https://openrouter.ai/api/v1 | No |
PROVIDERS__OPENROUTER__DEFAULT_MODEL | src/storymatrix/config/models.py:OpenRouterConfig | google/gemini-2.5-flash-lite | No |
PROVIDERS__OPENROUTER__HTTP_REFERER | src/storymatrix/config/models.py:OpenRouterConfig | https://noflippinway.lol | No |
PROVIDERS__OPENROUTER__X_TITLE | src/storymatrix/config/models.py:OpenRouterConfig | NoLoL | No |
PROVIDERS__OPENROUTER__TEMPERATURE | src/storymatrix/config/models.py:OpenRouterConfig | 0.7 | No |
PROVIDERS__OPENROUTER__MAX_TOKENS | src/storymatrix/config/models.py:OpenRouterConfig | 4096 | No |
PROVIDERS__OPENROUTER__MAX_RETRIES | src/storymatrix/config/models.py:OpenRouterConfig | 3 | No |
PROVIDERS__OPENROUTER__TIMEOUT_SECONDS | src/storymatrix/config/models.py:OpenRouterConfig | 120 | No |
Midjourney
| Variable | Consumer | Default | Secret? |
|---|---|---|---|
PROVIDERS__MIDJOURNEY__API_URL | src/storymatrix/config/models.py:MidjourneyConfig | host-specific; override it | No |
PROVIDERS__MIDJOURNEY__API_KEY | src/storymatrix/config/models.py:MidjourneyConfig | unset | Yes |
PROVIDERS__MIDJOURNEY__TIMEOUT_SECONDS | src/storymatrix/config/models.py:MidjourneyConfig | 240 | No |
PROVIDERS__MIDJOURNEY__MAX_RETRIES | src/storymatrix/config/models.py:MidjourneyConfig | 4 | No |
PROVIDERS__MIDJOURNEY__BOT_TYPE | src/storymatrix/config/models.py:MidjourneyConfig | MID_JOURNEY | No |
PROVIDERS__MIDJOURNEY__MODES | src/storymatrix/config/models.py:MidjourneyConfig | [FAST] | No |
PROVIDERS__MIDJOURNEY__POLL_INTERVAL_SECONDS | src/storymatrix/config/models.py:MidjourneyConfig | 15 | No |
PROVIDERS__MIDJOURNEY__QUEUE_BACKOFF_BASE_SECONDS | src/storymatrix/config/models.py:MidjourneyConfig | 15 | No |
PROVIDERS__MIDJOURNEY__QUEUE_BACKOFF_MAX_SECONDS | src/storymatrix/config/models.py:MidjourneyConfig | 25 | No |
PROVIDERS__MIDJOURNEY__SUBMIT_CONCURRENCY | src/storymatrix/config/models.py:MidjourneyConfig | 1 | No |
PROVIDERS__MIDJOURNEY__UPSAMPLE_ENABLED | src/storymatrix/config/models.py:MidjourneyConfig | false | No |
PROVIDERS__MIDJOURNEY__UPSAMPLE_COUNT | src/storymatrix/config/models.py:MidjourneyConfig | 0 | No |
PROVIDERS__MIDJOURNEY__UPSAMPLE_INDICES | src/storymatrix/config/models.py:MidjourneyConfig | [] | No |
PlayAI
| Variable | Consumer | Default | Secret? |
|---|---|---|---|
PROVIDERS__PLAYAI__API_KEY | src/storymatrix/config/models.py:PlayAIConfig | unset | Yes |
PROVIDERS__PLAYAI__USER_ID | src/storymatrix/config/models.py:PlayAIConfig | unset | No |
PROVIDERS__PLAYAI__BASE_URL | src/storymatrix/config/models.py:PlayAIConfig | https://api.play.ht/api/v2 | No |
PROVIDERS__PLAYAI__DEFAULT_VOICE | src/storymatrix/config/models.py:PlayAIConfig | s3://voice-cloning-zero-shot/d9ff78ba-d016-47f6-b046-526a0004622e/alice/manifest.json | No |
PROVIDERS__PLAYAI__QUALITY | src/storymatrix/config/models.py:PlayAIConfig | high | No |
PROVIDERS__PLAYAI__STREAM_ENABLED | src/storymatrix/config/models.py:PlayAIConfig | true | No |
PROVIDERS__PLAYAI__TIMEOUT_SECONDS | src/storymatrix/config/models.py:PlayAIConfig | 60 | No |
PROVIDERS__PLAYAI__MAX_RETRIES | src/storymatrix/config/models.py:PlayAIConfig | 3 | No |
PROVIDERS__PLAYAI__OUTPUT_FORMAT | src/storymatrix/config/models.py:PlayAIConfig | mp3 | No |
Strategy selectors
| Variable | Consumer | Default | Secret? |
|---|---|---|---|
PROVIDERS__STRATEGY__LLM_PROVIDER | src/storymatrix/config/models.py:ProviderStrategy | openrouter | No |
PROVIDERS__STRATEGY__AGENTIC_TIMELINE_PROVIDER | src/storymatrix/config/models.py:ProviderStrategy | openrouter | No |
PROVIDERS__STRATEGY__TTS_PROVIDER | src/storymatrix/config/models.py:ProviderStrategy | piper | No |
PROVIDERS__STRATEGY__SFX_PROVIDER | src/storymatrix/config/models.py:ProviderStrategy | local | No |
PROVIDERS__STRATEGY__MUSIC_PROVIDER | src/storymatrix/config/models.py:ProviderStrategy | local | No |
PROVIDERS__STRATEGY__IMAGE_PROVIDER | src/storymatrix/config/models.py:ProviderStrategy | mock | No |
🖼️ DALLE_
| Variable | Consumer | Default | Secret? |
|---|---|---|---|
DALLE_API_KEY | src/storymatrix/config/models.py:DalleConfig | unset | Yes |
DALLE_BASE_URL | src/storymatrix/config/models.py:DalleConfig | https://api.openai.com/v1 | No |
DALLE_MODEL | src/storymatrix/config/models.py:DalleConfig | dall-e-3 | No |
DALLE_ORGANIZATION_ID | src/storymatrix/config/models.py:DalleConfig | unset | No |
DALLE_MAX_RETRIES | src/storymatrix/config/models.py:DalleConfig | 3 | No |
DALLE_TIMEOUT_SECONDS | src/storymatrix/config/models.py:DalleConfig | 120 | No |
🎼 MUSICGEN_
| Variable | Consumer | Default | Secret? |
|---|---|---|---|
MUSICGEN_API_KEY | src/storymatrix/config/models.py:MusicGenConfig | unset | Yes |
MUSICGEN_MODEL_ID | src/storymatrix/config/models.py:MusicGenConfig | facebook/musicgen-small | No |
MUSICGEN_TIMEOUT_SECONDS | src/storymatrix/config/models.py:MusicGenConfig | 120 | No |
📈 Telemetry
| Variable | Consumer | Default | Secret? |
|---|---|---|---|
OTEL_EXPORTER_OTLP_ENDPOINT | src/storymatrix/infrastructure/observability/tracing.py | unset; enabling OTLP requires it | No |
OTEL_SERVICE_NAME | OpenTelemetry SDK (not read by application code) | SDK-defined | No |
OTEL_RESOURCE_ATTRIBUTES | OpenTelemetry SDK (not read by application code) | unset | No |
OTEL_CONSOLE_EXPORTER | src/storymatrix/cli/main.py; src/storymatrix/interfaces/api/main.py; src/storymatrix/interfaces/web/main.py | false | No |
DEPLOYMENT_ENVIRONMENT | src/storymatrix/cli/main.py; src/storymatrix/interfaces/api/main.py; src/storymatrix/interfaces/web/main.py | development | No |
See ⚙️ Configuration for the nested settings tree and 📈 Observability for metrics and tracing behavior.