Settings

The Settings tab centralizes application-wide options. Changes are staged in the form until you click Save Changes — use Discard to revert the unsaved edits. The full schema is also accessible through the API reference (GET /api/settings, PUT /api/settings).

UI Settings

Controls for the web interface appearance.

• Language — interface language. Options: English, Turkish, Spanish, German, Ukrainian, French, Greek, Italian, Dutch, Korean, Brazilian Portuguese, Traditional Chinese, Simplified Chinese, Arabic. Default: English.
• Time Format — how times are rendered in the UI. Options: 24-hour (14:30) or 12-hour (2:30 PM). Default: 24-hour.

Workspace Settings

Controls for workspace persistence across sessions. See Workspaces for background on what a workspace contains.

• Restore Last Workspace on Startup — when enabled, MZAP automatically reopens the workspace that was active when the application last closed. Default: on.
• Save Workspace on Exit — when enabled, MZAP writes pending workspace changes to disk before shutting down. Default: on.
• Auto-Save Interval (minutes) — how often MZAP writes workspace changes to disk during normal operation. Default: 5. Range: 0–60. Set to 0 to disable auto-save (save only on exit or on manual save).

Launch on Windows startup

The Launch on Windows Startup toggle starts MZAP automatically the next time you log into Windows. (Windows desktop app only.)

• Registration is per-user — it needs no administrator rights or UAC prompt and only affects the current Windows user.
• The toggle takes effect immediately; no restart is needed to register or unregister it.
• You can also disable it from Task Manager → Startup, where it appears as “MZAP”.
• The entry self-heals: if MZAP is updated and its install location changes, the startup registration is re-pointed at the new location automatically on the next launch.
• The window opens normally on auto-launch; the Restore Last Workspace on Startup setting above governs whether routing and playback resume.

Logging Settings

Controls for application log output. Logs are stored under %APPDATA%\MZAP\logs.

• Log Level — minimum severity written to the log file. Each level is inclusive: it captures itself plus all higher-severity levels.

  Setting	Captures
  Debug	Debug + Info + Warning + Error + Critical
  Info (default)	Info + Warning + Error + Critical
  Warning	Warning + Error + Critical
  Error	Error + Critical only

  Pick Debug when capturing traces for a support request — it is the most verbose option and records everything the app emits. Switch back to Info or Warning for day-to-day operation to keep log files small. Changes to the log level take effect on the next app restart.

• Max Log File Size (MB) — maximum size of a single log file before it is rotated. Default: 10. Range: 1–100.

• Open Log Files Folder — opens the log directory in the system file explorer. Useful when zipping logs to attach to a support ticket.

Audio Settings

Global audio playback behavior.

• Default Crossfade Duration (seconds) — fade-in/fade-out length applied when a track ends and the next one begins in the same player. Default: 5. Range: 0–10. Set to 0 to disable crossfading (hard cuts). This default can be overridden per playlist.

Strict zone channels

• Strict zone channels (one zone per channel) — controls whether two zones may target the same device channel. Default: off.
  • Off (default) — overlap is allowed; zones that share a channel sum their audio at that output. The Create/Edit Zone dialog lists every channel and labels occupied ones with the owning zone.
  • On — a channel may belong to only one zone. The dialog disables occupied channels and the API rejects an overlapping zone.

Network Access

Lets MZAP be controlled from other devices on the same network (other PCs, and — in future — mobile apps). By default MZAP binds to localhost only and is reachable just from the PC it runs on.

• Allow control from other devices on this network (ExposeToLocalNetwork, off by default) — binds the API and UI to all network interfaces so other devices can reach them.
• Restart required — the change takes effect only after MZAP is restarted; the UI shows a “restart required” banner until then.
• Confirmation flow — enabling exposure opens a dialog that warns authentication is off by default and offers to enable it in the same step, shows the LAN URL to use from other devices (e.g. http://192.168.1.20:5000, the API port that serves both the UI and the API), and explains the firewall requirement.
• Firewall — the installer has a second, unchecked-by-default task, “Allow access from other devices on your network (LAN)”, that adds LAN-scoped firewall rules (MZAP API (LAN) / MZAP UI (LAN)). The existing localhost-only rule is unchanged.

When exposure is on, opening http://<lan-ip>:5000 from another device connects to that machine’s API for both REST and live (SSE) updates.

Caution

Exposing MZAP to the network makes it reachable by anyone who can reach this PC. Enable authentication (see Users and Access) before exposing it on an untrusted network.

Network Stream Settings

Controls for internet radio and other network audio streams.

• Network Timeout (ms) — how long MZAP waits for a user-initiated stream load to succeed before giving up. Default: 50000. Range: 1000–60000.

• Network Buffer (ms) — size of the BASS network buffer. Larger buffers absorb more jitter at the cost of higher memory and longer start-up delay. Default: 10000. Range: 1000–30000.

• Pre-Buffer Percent — percentage of the network buffer that must fill before playback starts. Default: 0 (auto, calculated from buffer length). Range: 0–100.

• Playlist Mode — how playlist containers (.m3u, .pls, etc.) referenced by stream URLs are handled. Options:

  • Download First (default) — fetch the playlist, then play the first entry.
  • Disabled — treat the URL as a direct stream.

• Hide stream URLs for all players — when enabled, player cards and the player detail panel show only the hostname of the stream URL (e.g. radio.example.com) instead of the full URL. Applies to HTTP-based stream URLs only and is the global default for every player. Use this when feeds are licensed or otherwise considered sensitive. Default: off.

• Show stream URL hide toggle on players — when enabled, an eye icon appears next to Now Playing on each player card so admins can override the visibility of that player’s stream URL. The toggle is shown only to admin users and only when the player is loaded from an HTTP URL. Default: off. Per-player state is backed by PUT /api/players/{id}/stream-url-hidden.

  The per-player toggle interacts with the global setting:

  • When Hide stream URLs for all players is off, the toggle hides that single player’s URL. Other players keep showing the full URL.
  • When Hide stream URLs for all players is on, the toggle works in reverse — it reveals that one player’s URL while every other player stays hidden.

  This lets you globally hide all URLs and selectively unhide one player (e.g. when troubleshooting a feed) without flipping the global setting.

Stream resilience (advanced)

These options are managed through the API (PUT /api/settings) and keep unattended deployments playing through stalls, dead streams, and extended upstream outages.

Fast stall skip

When a stream stalls longer than the configured threshold, MZAP automatically skips to the next track in the playlist instead of waiting for the stream to recover. Both BASS buffer stalls and position-stuck scenarios (the stream reports Playing but the audio position stops advancing) are detected.

• StreamStallSkipEnabled — on by default. Toggle off to restore the previous wait-for-recovery behavior.
• StreamStallSkipSeconds — how long a stall must persist before skipping. Default: 3. Range: 1–30.

Short auto-advance timeout

Auto-advance loads (moving to the next track when the current one finishes) use a shorter network timeout than user-initiated loads, so dead streams fail fast and the playlist keeps cycling.

• StreamAutoAdvanceTimeoutMs — timeout for auto-advance stream loads. Default: 8000 (8s). Range: 2000–30000. User-initiated loads continue to use the full Network Timeout.

Persistent stream health retry

After the exponential-backoff retry attempts are exhausted, MZAP continues retrying at a fixed interval indefinitely instead of giving up. This keeps long-running unattended deployments alive through extended upstream outages.

• StreamHealthRetryIntervalSeconds — retry interval after backoff is exhausted. Default: 60. Range: 10–300. Set to 0 to restore the legacy “give up after backoff” behavior.

Network User-Agent

• NetworkUserAgent — User-Agent header sent to stream servers. Defaults to a modern Chrome identifier. Override when a stream host rejects non-browser agents or requires a specific identifier.

Prayer-Time Scheduling

Configures the venue location and calculation parameters used by Prayer Time scheduler triggers. The section is collapsed by default; expand it to enter values. While unconfigured, the Prayer Time trigger type in the scheduler still appears but cannot be used.

• Venue latitude — decimal degrees, north positive, range -90 to 90. Leave empty to disable the prayer feature.

• Venue longitude — decimal degrees, east positive, range -180 to 180.

• Use device location — reads coordinates from the browser’s geolocation API and rounds to four decimal places (about 11 m precision). Requires HTTPS or localhost and the user’s permission. The “Find your coordinates” link opens latlong.net for manual lookup.

• Clear location — empties both latitude and longitude fields, which disables Prayer Time triggers until a new location is set.

• Calculation method — chooses the twilight angles used for Fajr and Isha. Pick the one used in your region:

  Method	Typical region
  Muslim World League (default)	Worldwide default
  Islamic Society of North America	North America
  Egyptian General Authority of Survey	Egypt, much of Africa
  University of Islamic Sciences, Karachi	Pakistan, India, Bangladesh
  Umm al-Qura, Makkah	Saudi Arabia
  Dubai	UAE
  Institute of Geophysics, Tehran	Iran (Sunni & Shia)
  Shia Ithna Ashari, Qum	Shia communities (Ja’fari fiqh)

• Asr juristic method — Standard (Shafi’i, Maliki, Hanbali, Ja’fari — shadow length equals object length) or Hanafi (shadow length equals twice the object length, which pushes Asr later in the afternoon).

• High-latitude rule — adjustment for venues above roughly 48° latitude where the sun never reaches the standard twilight angles in summer or winter. Options:

  • None — use the raw astronomical calculation (may produce no Fajr/Isha at extreme latitudes).
  • Middle of the night — use the midpoint between Maghrib and Sunrise as a fallback.
  • One-seventh of the night — split the night into seven parts.
  • Angle-based — scale the night fraction proportionally to the configured twilight angle.

• Today’s prayer times — preview panel that calls GET /api/prayer/today and displays the five times for the current day in the venue’s local time zone, formatted using your Time Format preference. The panel auto-saves the prayer fields before computing, so you can sanity-check edits without first hitting the global Save Changes button. Use it after picking a method to verify the times match what your community expects.

The venue’s time zone is taken from the host system’s local time zone — there is no separate venue-time-zone setting yet, so run MZAP on a machine set to the venue’s local time.

API endpoints exposed by this feature:

• GET /api/prayer/today — five prayer times for today
• GET /api/prayer/{date} — five prayer times for a specific date (YYYY-MM-DD)

Both return a 400 when the venue location is not configured.

Text-to-speech

Configures the providers used by TTS jingles. The section shows a status row for each provider:

• Windows TTS — always available, no setup needed (offline, uses the host machine’s installed voices).
• Azure Speech (cloud) — disabled until the Cloud TTS license feature is present and an API key + region are configured.
• ElevenLabs (cloud) — disabled until the Cloud TTS license feature is present and an API key is configured.

Cloud TTS keys are encrypted and scoped to the current Windows user. They are never returned by any API endpoint and never included in workspace exports.

Setting up Azure Speech (optional)

Azure Speech gives you ~140 neural voices across 90+ languages. It is optional — the built-in Windows voices work offline with no setup. To use Azure you supply your own API key; Microsoft offers a free tier (F0) covering roughly 0.5 million characters per month.

1. Create a free Azure account at azure.microsoft.com/free (no charge; the free Speech tier needs no credit-card spend).
2. In the Azure Portal, choose Create a resource, search for Speech, and select Speech Services → Create.
3. Set:
   • Resource group — create one or reuse an existing group.
   • Region — pick a region near you (for example westus, eastus, westeurope). Note it down — MZAP asks for it.
   • Name — any name, e.g. mzap-tts.
   • Pricing tier — Free F0 for trial use, or Standard S0 for production volume.
4. After the resource deploys, open it and select Keys and Endpoint.
5. Copy KEY 1 and note the Location/Region.
6. In MZAP, go to Settings → Text-to-speech → Azure Speech → Set up key, paste the key and region, click Test connection, then Save.

Setting up ElevenLabs (optional)

ElevenLabs provides premium, multilingual neural voices. It is optional — the built-in Windows voices work offline with no setup. To use ElevenLabs you supply your own API key; ElevenLabs offers a free tier (~10,000 credits/month, roughly 10 minutes of generated audio).

1. Create an account at elevenlabs.io. No credit card is needed for the free tier.

2. Open your profile menu (top-right) → API Keys, or go directly to elevenlabs.io/app/settings/api-keys.

3. Click Create API Key and give it a name (e.g. MZAP).

4. Important — endpoint permissions. If you enable Restrict Key, you must grant the key access to both of these endpoints, or MZAP cannot use it:

   • Text to Speech → Access
   • Voices → Access

   MZAP needs Voices to list the available voices and to validate the key, and Text to Speech to generate the audio. A key restricted to Text to Speech only will fail the connection test with a 401 error. If in doubt, leave Restrict Key off — that grants all endpoints.

5. Copy the generated key (it starts with sk_). You won’t be able to see it again after closing the dialog.

6. In MZAP, go to Settings → Text-to-speech → ElevenLabs → Set up key, paste the key, click Test connection, then Save.

Once saved, ElevenLabs appears in the Provider dropdown when you create a TTS jingle. Its voices are multilingual — a single voice can speak any supported language, so you can type text in any language regardless of the voice’s listed accent.

Quota

The free tier’s monthly credit allowance does not roll over. MZAP only spends credits when a jingle’s text/voice/rate actually changes (synthesis is cached) — replaying or rescheduling an unchanged jingle is free. The Preview button also consumes credits each press. Check remaining quota on the ElevenLabs dashboard under Usage.

Both cloud providers require the Cloud TTS license feature — if a provider is greyed out in Settings, your license does not include it.

API Documentation

At the bottom of the Settings tab, Scalar API Docs opens the interactive API reference for the local MZAP instance in your browser. Use it to try endpoints against the running application. The same reference is available here in the docs under API Reference.