Wizarr

https://github.com/wizarrrr/wizarr
Admin
Wizarr is an automatic user invitation system for Plex, Jellyfin, and Emby, simplifying server...
Tokens:70,403
Snippets:613
Trust Score:8.1
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Welcome Message (Post-Invite) Markdown

Source: https://github.com/wizarrrr/wizarr/blob/main/docs/using-wizarr/pre-post-invite-steps.md

Use as a post-invite step to welcome new users and guide them through initial setup.

```markdown
# Welcome to Our Media Server! 🎉

Congratulations! Your account has been created successfully.

## What's Next?

1. **Open the Plex app** you downloaded earlier
2. **Sign in** with your Plex account
3. **Look for our server** in your server list
4. **Start watching!**

## Need Help?

Join our Discord community for support and updates:

[Join Discord](https://discord.gg/example){:target="_blank" .btn}
```

--------------------------------

### Python example: get status and create invitation

Source: https://github.com/wizarrrr/wizarr/blob/main/docs/API.md

Python script demonstrating how to call the /status endpoint and create an invitation. It sets the API key header, sends a POST request with JSON data, and prints the invitation URL on success.

```python
import requests

API_KEY = "your_api_key_here"
BASE_URL = "http://your-wizarr-instance/api"
headers = {"X-API-Key": API_KEY}

# Get system status
response = requests.get(f"{BASE_URL}/status", headers=headers)
print(response.json())

# Create invitation
data = {
    "server_ids": [1],
    "expires_in_days": 7,
    "duration": "30",
    "unlimited": False
}

response = requests.post(
    f"{BASE_URL}/invitations",
    headers={**headers, "Content-Type": "application/json"},
    json=data
)

if response.status_code == 201:
    invitation = response.json()
    print(f"Invitation URL: {invitation['invitation']['url']}")
```

--------------------------------

### Start Docker Compose services

Source: https://github.com/wizarrrr/wizarr/blob/main/docs/getting-started/installation.md

Starts all services defined in the Compose file. Both docker compose and docker-compose commands are shown.

```bash
docker compose up -d
```

```bash
docker-compose up -d
```

--------------------------------

### Login Page Example

Source: https://github.com/wizarrrr/wizarr/blob/main/docs/using-wizarr/ldap-authentication.md

Example of the login page when LDAP authentication is selected. The admin enters their LDAP credentials after choosing 'LDAP' from the dropdown.

```text
Authentication Method: [LDAP ▼]
Username: [admin]
Password: [••••••]
```

--------------------------------

### Basic Markdown Step Example

Source: https://github.com/wizarrrr/wizarr/blob/main/docs/using-wizarr/customise-steps.md

Shows the standard Markdown syntax supported by Wizarr for step content, including headings, lists, links, and button styling. Use this as a template for simple wizard steps.

```markdown
# Step Title

Welcome to our **media server**! Here's what you need to know:

## Getting Started

1. Download the app using the button below
2. Sign in with your username and password
3. Start enjoying your content!

[Download App](https://example.com/download){:target="_blank" .btn}
```

--------------------------------

### Mock System Setup and Failure Simulation

Source: https://github.com/wizarrrr/wizarr/blob/main/tests/README.md

Use this snippet to set up mock media server APIs for testing without requiring actual server instances. It initializes mock servers, creates a mock client for Jellyfin, and simulates server and user creation failures.

```python
from tests.mocks import create_mock_client, setup_mock_servers

# Setup
setup_mock_servers()

# Create mock client
mock_client = create_mock_client("jellyfin", server_id=1)

# Simulate failures
simulate_server_failure()
simulate_user_creation_failure(["problematic_username"])
```

--------------------------------

### Example directory structure for test media files

Source: https://github.com/wizarrrr/wizarr/blob/main/tests/test-media/movies/README.md

Shows the expected folder layout for test media files, with each movie in its own directory named 'Movie Name (Year)' containing a video file with the same name.

```text
movies/
├── Big Buck Bunny (2008)/
│   └── Big Buck Bunny (2008).mp4
└── Sintel (2010)/
    └── Sintel (2010).mp4
```

--------------------------------

### Run tests with uv

Source: https://github.com/wizarrrr/wizarr/blob/main/docs/contribute/development.md

Installs project dependencies (including development dependencies) with uv and then runs the test suite with pytest. Use this after cloning the repository and before contributing changes.

```bash
uv sync --locked
uv run pytest
```

--------------------------------

### Console Logging Output for Wizard Events

Source: https://github.com/wizarrrr/wizarr/blob/main/WIZARD_ARCHITECTURE.md

Example console output from the wizard controller, showing initialization, update events, button URLs, and phase indicator updates. Useful for verifying correct behavior during development.

```plaintext
WizardController initialized
✅ Wizard update: { newIdx: 1, maxIdx: 5, serverType: 'plex', phase: 'pre', requireInteraction: false }
Button wizard-prev-btn: URL=/pre-wizard/0, visible=true
Button wizard-next-btn: URL=/pre-wizard/2, visible=true
Phase indicator updated: pre
```

--------------------------------

### Require Interaction Step Example

Source: https://github.com/wizarrrr/wizarr/blob/main/docs/using-wizarr/customise-steps.md

Example step content that requires user interaction. When 'Require Interaction' is enabled, users must click at least one link or button before the Next button becomes active.

```markdown
# Download the Plex App

Before you can access our media library, you'll need to download the Plex app for your device.

**Choose your platform:**

[📱 Download for iOS](https://apps.apple.com/app/plex/id383457673){:target="_blank" .btn}
[🤖 Download for Android](https://play.google.com/store/apps/details?id=com.plexapp.android){:target="_blank" .btn}
[💻 Download for Windows](https://www.plex.tv/media-server-downloads/?cat=plex+desktop&plat=windows#plex-app){:target="_blank" .btn}

Click one of the download buttons above to continue.
```

--------------------------------

### Initialize Background Shimmer Particles

Source: https://github.com/wizarrrr/wizarr/blob/main/app/templates/welcome-jellyfin.html

Calls createShimmerParticles() to start the animated background effect on page load.

```javascript
createShimmerParticles();
```

--------------------------------

### LLDAP Directory Structure

Source: https://github.com/wizarrrr/wizarr/blob/main/docs/using-wizarr/ldap-authentication.md

Directory tree showing the expected LLDAP structure after setup, including the people and groups organizational units. The wizarr-service account and the wizarr_admins group are created during configuration, while john is created by Wizarr when an invitation is accepted.

```text
dc=example,dc=com
├── ou=people
│   ├── uid=admin
│   ├── uid=wizarr-service
│   └── uid=john (created by Wizarr)
└── ou=groups
    ├── cn=lldap_admin
    ├── cn=lldap_password_manager
    └── cn=wizarr_admins
```

--------------------------------

### Schedule activity summary polling every 15 seconds

Source: https://github.com/wizarrrr/wizarr/blob/main/app/activity/templates/activity/history_tab.html

Starts polling the activity summary every 15 seconds, but only if the activity table container exists. Also performs an immediate check on start.

```javascript
function scheduleActivitySummaryPolling() {
  const state = ensureActivityState();
  if (state.summaryTimer) {
    clearInterval(state.summaryTimer);
  }
  const container = document.getElementById('activity-table-container');
  if (!container) {
    return;
  }
  state.summaryTimer = setInterval(checkActivitySummary, 15000);
  checkActivitySummary();
}
```

--------------------------------

### Example LDAP User Entry

Source: https://github.com/wizarrrr/wizarr/blob/main/docs/using-wizarr/ldap-authentication.md

Example LDAP user entry created after invitation acceptance. The user is not automatically added to any groups; you must manually add them to the lldap_password_manager group via LLDAP's web UI to enable password changes.

```text
dn: uid=john,ou=people,dc=example,dc=com
objectClass: person
uid: john
mail: john@example.com
```

--------------------------------

### Start activity summary polling on page load

Source: https://github.com/wizarrrr/wizarr/blob/main/app/activity/templates/activity/history_tab.html

Initiates the polling loop for activity summary updates when the page loads.

```javascript
scheduleActivitySummaryPolling();
```

--------------------------------

### Activity table template with error/empty states and pagination

Source: https://github.com/wizarrrr/wizarr/blob/main/app/activity/templates/activity/_activity_table.html

Jinja template for the activity table. Handles error and empty states, iterates sessions to compute duration and playback info, renders a table with user, server, media, playback, device, duration, and started columns, and includes pagination controls when total_pages > 1.

```jinja
{% if error %}

### {{ _("Unable to load activity data") }}

{{ error }}

{% elif not sessions %}

### {{ _("No activity found") }}

{{ _("No media sessions found for the selected period") }}

{% else %}

{% for session in sessions %}
{% set duration_seconds = session.display_duration_seconds %}
{% set duration_str = "" %}
{% if duration_seconds %}
{% set total_minutes = (duration_seconds // 60) | int %}
{% set hours = (total_minutes // 60) | int %}
{% set minutes = (total_minutes % 60) | int %}
{% if hours > 0 %}
{% set duration_str = "{}h {}m".format(hours, minutes) %}
{% else %}
{% set duration_str = "{}m".format(minutes) %}
{% endif %}
{% endif %}
{% set playback_info = session.get_transcoding_info() %}
{% set is_transcoding = playback_info.get("is_transcoding") %}
{% set is_direct_play = playback_info.get("direct_play") %}
{% set is_remux = (playback_info|length > 0 and not is_transcoding and not is_direct_play) %}
{% set video_codec = playback_info.get("video_codec") %}
{% set audio_codec = playback_info.get("audio_codec") %}
{% set video_resolution = playback_info.get("video_resolution") %}
{% set container = playback_info.get("container") %}
{% set transcoding_speed = playback_info.get("transcoding_speed") %}
{% endfor %}

| {{ _("User") }} | {{ _("Server") }} | {{ _("Media") }} | {{ _("Playback") }} | {{ _("Device") }} | {{ _("Duration") }} | {{ _("Started") }} |
| --- | --- | --- | --- | --- | --- | --- |
| {{ session.display_user_name }} | {% if session.server_type and session.server_name %} {{ session.server_type|server_name_tag(session.server_name) }} {% else %} {{ _("Unknown") }} {% endif %} | {{ session.media_title }} {% if session.series_name %} {{ session.series_name }} {% if session.season_number and session.episode_number %} • S{{ session.season_number }}E{{ session.episode_number }} {% endif %} {% endif %} {% if session.media_type %} {{ session.media_type }} {% endif %} | {% if is_transcoding %} {% set playback_label = _("Transcoding") %} {% set playback_dot = "bg-orange-500" %} {% set playback_hint = _('Video or audio is being transcoded for this session.') %} {% elif is_remux %} {% set playback_label = _("Remuxing") %} {% set playback_dot = "bg-blue-500" %} {% set playback_hint = _('Container remux without video transcoding.') %} {% elif is_direct_play %} {% set playback_label = _("Direct Play") %} {% set playback_dot = "bg-green-500" %} {% set playback_hint = _('Media is direct playing without conversion.') %} {% else %} {% set playback_label = _("Unknown") %} {% set playback_dot = "bg-gray-400" %} {% set playback_hint = _('Playback method unknown – no stream details reported.') %} {% endif %} {{ playback_label }} {% if transcoding_speed and is_transcoding %} {{ "%.1f"|format(transcoding_speed|float) }}x {% endif %} | {{ session.device_name or session.client_name or _("Unknown Device") }} | {% if session.is_active and session.started_at %} 00:00 {{ _("Live") }} {% elif duration_str %} {{ duration_str }} {% else %} {{ _("N/A") }} {% endif %} | {{ session.started_at|local_date if session.started_at else '-' }} |

{{ _("Transcoding") }} {{ _("Remuxing") }} {{ _("Direct Play") }} {{ _("Unknown") }} {{ _("Hover a state for stream details.") }}

{% if total_pages > 1 %}

{{ _("Showing") }} {{ ((page - 1) * 20) + 1 }} {{ _("to") }} {{ ((page - 1) * 20) + sessions|length }} {{ _("of") }} {{ total_count }} {{ _("entries") }}
{% from '_partials/macros.html' import numbered_pagination %}
{{ numbered_pagination(page, total_pages) }}

{% endif %}
{% endif %}
```

--------------------------------

### LLDAP Docker Compose Setup

Source: https://github.com/wizarrrr/wizarr/blob/main/docs/using-wizarr/ldap-authentication.md

Docker Compose configuration for LLDAP, a lightweight LDAP server. Sets the LDAP port to 3890 and the web UI to 17170, with environment variables for JWT secret, admin password, and base DN. Requires changing the placeholder values before use.

```yaml
version: '3'
services:
  lldap:
    image: lldap/lldap:stable
    ports:
      - "3890:3890"  # LDAP port
      - "17170:17170"  # Web UI
    environment:
      - LLDAP_JWT_SECRET=CHANGE_ME_TO_RANDOM_STRING
      - LLDAP_LDAP_USER_PASS=CHANGE_ME_ADMIN_PASSWORD
      - LLDAP_LDAP_BASE_DN=dc=example,dc=com
    volumes:
      - lldap_data:/data

volumes:
  lldap_data:
```

--------------------------------

### Nginx SWAG reverse proxy configuration for wizarr

Source: https://github.com/wizarrrr/wizarr/blob/main/docs/getting-started/reverse-proxy.md

Use this Nginx server block for SWAG (LinuxServer.io) reverse proxy setups. Place it in a file named `wizarr.subdomain.conf` under the `proxy-confs` directory. It listens on port 443 with SSL, sets `client_max_body_size` to 0, and proxies requests to the internal wizarr service on port 5690.

```nginx
server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;

    server_name wizarr.*;

    include /config/nginx/ssl.conf;

    client_max_body_size 0;

    location / {
        include /config/nginx/proxy.conf;
        resolver 127.0.0.11 valid=30s;
        set $upstream_app wizarr;
        set $upstream_port 5690;
        set $upstream_proto http;
        proxy_pass $upstream_proto://$upstream_app:$upstream_port;
    }

}
```

--------------------------------

### File Structure for Legacy Steps

Source: https://github.com/wizarrrr/wizarr/blob/main/docs/using-wizarr/customise-steps.md

Shows the required directory and file layout for legacy file-based steps. Each server type (plex, jellyfin, emby, etc.) has its own folder with numbered markdown files.

```text
wizard_steps/
├── plex/
│   ├── 01_download.md
│   ├── 02_setup.md
│   └── 99_tips.md
├── jellyfin/
│   ├── 01_download.md
│   └── 02_about.md
├── emby/
│   ├── 01_download.md
│   └── 02_about.md
├── audiobookshelf/
│   └── 01_intro.md
├── romm/
│   └── 01_intro.md
└── komga/
    ├── 01_intro.md
    ├── 02_access.md
    ├── 03_features.md
    └── 04_tips.md
```

--------------------------------

### App Download (Pre-Invite) Markdown

Source: https://github.com/wizarrrr/wizarr/blob/main/docs/using-wizarr/pre-post-invite-steps.md

Use as a pre-invite step to prompt users to download the Plex app. Enable "Require Interaction" to ensure users download the app before joining.

```markdown
# Download the Plex App

To access our media library, you'll need the Plex app installed on your device.

**Choose your platform:**

[📱 iOS](https://apps.apple.com/app/plex/id383457673){:target="_blank" .btn}
[🤖 Android](https://play.google.com/store/apps/details?id=com.plexapp.android){:target="_blank" .btn}
[💻 Windows](https://www.plex.tv/media-server-downloads/){:target="_blank" .btn}
[🍎 macOS](https://www.plex.tv/media-server-downloads/){:target="_blank" .btn}

Click a download button above to continue.
```

--------------------------------

### Pre-wizard route: /pre-wizard/<int:idx>

Source: https://github.com/wizarrrr/wizarr/blob/main/WIZARD_ARCHITECTURE.md

Pre-wizard route that validates the invite code, fetches pre-invite steps, and renders the wizard with the 'pre' phase, passing a completion URL and label.

```python
@wizard_bp.route("/pre-wizard/<int:idx>")
def pre_wizard(idx: int = 0):
    # Validate invite code
    invite_code = InviteCodeManager.get_invite_code()
    # ... validation logic ...

    # Get pre-invite steps
    steps = _steps(server_type, cfg, category="pre_invite")

    # Render with pre-phase context
    return _serve_wizard(
        server_type, idx, steps, "pre",
        completion_url=url_for("wizard.pre_wizard_complete"),
        completion_label=_("Continue to Invite")
    )
```

--------------------------------

### Conditional Logic with requires Field

Source: https://github.com/wizarrrr/wizarr/blob/main/docs/using-wizarr/customise-steps.md

Use the `requires` field to conditionally show steps. This example shows a Discord integration step that only appears if `discord_url` is set in the `requires` field.

```markdown
# Discord Integration

Join our Discord community for support and updates!

[Join Discord]({{ discord_url }}){:target="_blank" .btn}
```

--------------------------------

### Dynamic Content with Template Variables

Source: https://github.com/wizarrrr/wizarr/blob/main/docs/using-wizarr/customise-steps.md

Use template variables like `{{ server_name }}` and `{{ server_url }}` to inject server settings into step content. This allows steps to display dynamic information.

```markdown
Welcome to **{{ server_name }}**!

Your server is available at: {{ server_url }}
```

--------------------------------

### Run Tests with Coverage

Source: https://github.com/wizarrrr/wizarr/blob/main/tests/README.md

Runs tests with coverage for the invitation manager and invites services, generating an HTML report.

```bash
uv run pytest tests/ --cov=app/services/invitation_manager --cov=app/services/invites --cov-report=html
```

--------------------------------

### Post-wizard route: /post-wizard/<int:idx>

Source: https://github.com/wizarrrr/wizarr/blob/main/WIZARD_ARCHITECTURE.md

Post-wizard route that checks authentication, fetches post-invite steps, and renders the wizard with the 'post' phase.

```python
@wizard_bp.route("/post-wizard/<int:idx>")
def post_wizard(idx: int = 0):
    # Check authentication
    if not current_user.is_authenticated and not session.get("wizard_access"):
        return redirect(url_for("auth.login"))

    # Get post-invite steps
    steps = _steps(server_type, cfg, category="post_invite")

    # Render with post-phase context
    return _serve_wizard(server_type, idx, steps, "post")
```

--------------------------------

### JavaScript DOMContentLoaded Handler for Invitation Flow

Source: https://github.com/wizarrrr/wizarr/blob/main/app/templates/welcome-jellyfin.html

Initializes the invitation flow, retrieves DOM elements, and defines functions for typewriter effect, particle creation, and form reveal. It also starts the shimmer particle creation on page load.

```javascript
document.addEventListener('DOMContentLoaded', function() {
    const acceptBtn = document.getElementById('accept-invite-btn');
    const backBtn = document.getElementById('back-btn');
    const welcomeScreen = document.getElementById('welcome-screen');
    const formScreen = document.getElementById('form-screen');
    const cardContainer = document.getElementById('card-container');
    const mainContainer = document.getElementById('main-container');
    const pageHeader = document.getElementById('page-header');
    const pageFooter = document.getElementById('page-footer');
    const form = document.querySelector('form[action="{{ url_for("public.process_invitation") }}"]');
    const submitBtn = document.getElementById('submit-btn');
    const btnText = document.getElementById('btn-text');
    const btnLoading = document.getElementById('btn-loading');
    const buttonText = document.getElementById('button-text');
    const layoutWrapper = mainContainer.parentElement;
```

--------------------------------

### Anime.js animations and form handling

Source: https://github.com/wizarrrr/wizarr/blob/main/app/templates/welcome-jellyfin.html

This script handles animations for the welcome screen, including a cubic bezier easing, mobile header/footer animations, form field focus/blur effects, form submission with loading state, keyboard navigation (ESC and Enter), and auto-focus management using MutationObserver.

```javascript
'cubicBezier(0.25, 0.46, 0.45, 0.94)' }, 0); // Mobile: Show header and footer again when going back if (isMobile) { timeline.add([pageHeader, pageFooter], { opacity: 1, translateY: 0, duration: 400, ease: 'outQuad' }, 200); // Start after container animation begins } }); // Enhanced form field animations with Anime.js const inputs = form.querySelectorAll('input'); inputs.forEach(input => { input.addEventListener('focus', function() { anime.animate(this.parentElement, { translateY: -2, duration: 200, ease: 'outQuad' }); }); input.addEventListener('blur', function() { anime.animate(this.parentElement, { translateY: 0, duration: 200, ease: 'outQuad' }); }); }); // Form submission handling with enhanced animations form.addEventListener('submit', function(e) { const currentSubmitBtn = document.getElementById('submit-btn'); const currentBtnText = currentSubmitBtn.querySelector('#button-text') || currentSubmitBtn.querySelector('#btn-text'); const currentBtnLoading = document.getElementById('btn-loading'); if (currentSubmitBtn) { // Disable button and show loading state with animation currentSubmitBtn.disabled = true; currentSubmitBtn.classList.add('loading-gradient'); anime.animate(currentSubmitBtn, { scale: [1, 0.98, 1], duration: 200, ease: 'outQuad' }); // Show loading state if (currentBtnText) currentBtnText.classList.add('hidden'); if (currentBtnLoading) currentBtnLoading.classList.remove('hidden'); // Re-enable button after 5 seconds as fallback setTimeout(function() { currentSubmitBtn.disabled = false; currentSubmitBtn.classList.remove('loading-gradient'); if (currentBtnText) currentBtnText.classList.remove('hidden'); if (currentBtnLoading) currentBtnLoading.classList.add('hidden'); }, 5000); } }); // Keyboard navigation enhancements document.addEventListener('keydown', function(e) { // ESC to go back from form to welcome if (e.key === 'Escape' && formScreen.style.opacity === '1') { backBtn.click(); } // Enter to accept invitation from welcome screen if (e.key === 'Enter' && welcomeScreen.style.opacity !== '0' && !acceptBtn.disabled) { acceptBtn.click(); } }); // Auto-focus management const observer = new MutationObserver((mutations) => { mutations.forEach((mutation) => { if (mutation.type === 'attributes' && mutation.attributeName === 'style') { const target = mutation.target; if (target === formScreen && formScreen.style.opacity === '1') { setTimeout(() => { const firstInput = form.querySelector('input:not([type="hidden"])'); if (firstInput) firstInput.focus(); }, 100); } } }); }); observer.observe(formScreen, { attributes: true }); });
```

--------------------------------

### Backward Compatibility Endpoint for /wizard/

Source: https://github.com/wizarrrr/wizarr/blob/main/WIZARD_ARCHITECTURE.md

Redirects to the appropriate wizard phase based on authentication and invite code presence. If the user is authenticated or has wizard access, it goes to post-wizard; otherwise, it checks for an invite code to go to pre-wizard, falling back to the public root.

```python
@wizard_bp.route("/")
def start():
    """Redirect to appropriate wizard based on context."""
    if current_user.is_authenticated or session.get("wizard_access"):
        return redirect(url_for("wizard.post_wizard"))

    invite_code = InviteCodeManager.get_invite_code()
    if invite_code:
        return redirect(url_for("wizard.pre_wizard"))

    return redirect(url_for("public.root"))
```

--------------------------------

### Live timers for now playing cards

Source: https://github.com/wizarrrr/wizarr/blob/main/app/templates/admin/home.html

Functions to start live timers for timestamp elements and now-playing cards, updating time displays and progress bars every second. Includes formatDuration to format seconds as HH:MM:SS or MM:SS.

```javascript
let liveTimers = [];
let nowPlayingTimers = [];

function startLiveTimers() {
  // Find all live timestamp elements and start their timers
  document.querySelectorAll('[data-timestamp]').forEach(function(elem) {
    const timestamp = parseInt(elem.getAttribute('data-timestamp'));
    if (timestamp) {
      const timer = setInterval(function() {
        const now = Math.floor(Date.now() / 1000);
        const diff = now - timestamp;
        elem.textContent = formatDuration(diff);
      }, 1000);
      liveTimers.push(timer);
    }
  });
}

function startNowPlayingTimers() {
  // Clear existing timers
  nowPlayingTimers.forEach(timer => clearInterval(timer));
  nowPlayingTimers = [];

  // Find all now playing cards and start live time updates
  document.querySelectorAll('.now-playing-card[data-session-state="playing"]').forEach(function(card) {
    const duration = parseInt(card.getAttribute('data-session-duration')) || 0;
    const initialPosition = parseInt(card.getAttribute('data-session-position')) || 0;
    const sessionId = card.getAttribute('data-session-id');

    if (duration > 0 && sessionId) {
      let currentPosition = initialPosition;
      const startTime = Date.now();

      const timer = setInterval(function() {
        // Calculate elapsed time since timer started (in milliseconds)
        const elapsed = Date.now() - startTime;
        // Add elapsed time to initial position
        const newPosition = currentPosition + elapsed;
        // Don't exceed duration
        if (newPosition < duration) {
          updateCardTime(card, newPosition, duration);
        } else {
          clearInterval(timer);
        }
      }, 1000);
      nowPlayingTimers.push(timer);
    }
  });
}

function updateCardTime(card, position, duration) {
  const timeDisplay = card.querySelector('.session-time-display');
  const progressBar = card.querySelector('.session-progress-bar');

  if (timeDisplay) {
    const posSeconds = Math.floor(position / 1000);
    const durSeconds = Math.floor(duration / 1000);
    const posMins = Math.floor(posSeconds / 60);
    const durMins = Math.floor(durSeconds / 60);
    const posSecsRemainder = posSeconds % 60;
    const durSecsRemainder = durSeconds % 60;
    timeDisplay.textContent = `${posMins}:${posSecsRemainder.toString().padStart(2, '0')} / ${durMins}:${durSecsRemainder.toString().padStart(2, '0')}`;
  }

  if (progressBar && duration > 0) {
    const progressPercent = (position / duration) * 100;
    progressBar.style.width = `${Math.min(progressPercent, 100)}%`;
  }
}

function formatDuration(seconds) {
  const hours = Math.floor(seconds / 3600);
  const minutes = Math.floor((seconds % 3600) / 60);
  const secs = seconds % 60;
  if (hours > 0) {
    return `${hours}:${minutes.toString().padStart(2, '0')}:${secs.toString().padStart(2, '0')}`;
  }
  return `${minutes}:${secs.toString().padStart(2, '0')}`;
}
```

--------------------------------

### JavaScript initialization for timers and popovers

Source: https://github.com/wizarrrr/wizarr/blob/main/app/templates/admin/home.html

Initializes live timers, now playing timers, and Flowbite popovers on DOMContentLoaded. Includes a comment about removed adaptive additionalWidgets logic.

```javascript
document.addEventListener('DOMContentLoaded', function() { // Initialize live timers startLiveTimers(); // Initialize now playing timers startNowPlayingTimers(); // Initialize Flowbite popovers reinitFlowbitePopovers(); // Removed adaptive additionalWidgets logic since those widgets are no longer present });
```

--------------------------------

### Terms of Service (Pre-Invite) Markdown

Source: https://github.com/wizarrrr/wizarr/blob/main/docs/using-wizarr/pre-post-invite-steps.md

Use as a pre-invite step to display terms of service. Enable "Require Interaction" to ensure users click the terms link before proceeding.

```markdown
# Terms of Service

Before joining our media server, please read and acknowledge our terms:

## Server Rules

1. **No sharing** - Keep your account credentials private
2. **Respect bandwidth** - Don't download excessively during peak hours
3. **Content requests** - Use Overseerr for new content requests
4. **Be respectful** - This is a community resource

By clicking "Next" and accepting this invitation, you agree to these terms.

[View Full Terms](https://example.com/terms){:target="_blank" .btn}
```

--------------------------------

### Run Wizarr container with same parameters

Source: https://github.com/wizarrrr/wizarr/blob/main/docs/getting-started/installation.md

Runs the container with the same parameters originally used to create it. The ellipsis indicates that the full command is the same as the original run command.

```bash
docker run -d ...
```

--------------------------------

### Request System Integration (Post-Invite) Markdown

Source: https://github.com/wizarrrr/wizarr/blob/main/docs/using-wizarr/pre-post-invite-steps.md

Use as a post-invite step to integrate with Overseerr for content requests.

```markdown
# Request New Content

Want to watch something that's not in our library? Use Overseerr to request it!

## How to Request Content

1. Visit our Overseerr instance
2. Sign in with your Plex account
3. Search for movies or TV shows
4. Click "Request" and we'll add it to the library

[Open Overseerr](https://overseerr.example.com){:target="_blank" .btn}
```

--------------------------------

### Run All Tests

Source: https://github.com/wizarrrr/wizarr/blob/main/tests/README.md

Runs the entire test suite with verbose output.

```bash
uv run pytest tests/ -v
```

--------------------------------

### Step filtering: _steps()

Source: https://github.com/wizarrrr/wizarr/blob/main/WIZARD_ARCHITECTURE.md

Helper that queries WizardStep rows filtered by server type and category (pre_invite or post_invite), ordered by position, with a fallback to legacy markdown files for post_invite only.

```python
def _steps(server: str, cfg: dict, category: str = "post_invite"):
    """Return ordered wizard steps for server and category.

    Args:
        server: Server type (plex, jellyfin, etc.)
        cfg: Configuration dictionary
        category: 'pre_invite' or 'post_invite' (default: 'post_invite')

    Returns:
        List of wizard steps filtered by category
    """
    db_rows = (
        WizardStep.query
        .filter_by(server_type=server, category=category)
        .order_by(WizardStep.position)
        .all()
    )
    # ... fallback to legacy markdown files (post_invite only) ...
```

--------------------------------

### Verify LDAP Configuration with ldapsearch

Source: https://github.com/wizarrrr/wizarr/blob/main/docs/using-wizarr/ldap-authentication.md

Use these ldapsearch commands to verify the service account bind, search for users, and search for groups in LLDAP.

```bash
# Test service account bind
ldapsearch -x -H ldap://lldap:3890 \
  -D "uid=wizarr-service,ou=people,dc=example,dc=com" \
  -w "SERVICE_ACCOUNT_PASSWORD" \
  -b "dc=example,dc=com"

# Search for users
ldapsearch -x -H ldap://lldap:3890 \
  -D "uid=wizarr-service,ou=people,dc=example,dc=com" \
  -w "SERVICE_ACCOUNT_PASSWORD" \
  -b "ou=people,dc=example,dc=com" \
  "(uid=john)"

# Search for groups
ldapsearch -x -H ldap://lldap:3890 \
  -D "uid=wizarr-service,ou=people,dc=example,dc=com" \
  -w "SERVICE_ACCOUNT_PASSWORD" \
  -b "ou=groups,dc=example,dc=com" \
  "(objectClass=groupOfUniqueNames)"
```

--------------------------------

### Template with Translation and Widget

Source: https://github.com/wizarrrr/wizarr/blob/main/docs/using-wizarr/customise-steps.md

Demonstrates using template variables, translation, and a button widget in a shared bundle. Note that loops, assignments, macros, and arbitrary function calls are not supported.

```markdown
|||
## {{ _("Welcome") }}

{{ server_name }}

{{ widget:button url="external_url" text=_("Open") }}
|||
```

--------------------------------

### Flask route pattern: _serve_wizard

Source: https://github.com/wizarrrr/wizarr/blob/main/WIZARD_ARCHITECTURE.md

Core Flask route helper for wizard pages. Selects the base template (frame.html) for initial loads or the HTMX partial (_content.html) for swaps, renders the template with phase and completion context, and adds X-Wizard-* headers for HTMX requests.

```python
def _serve_wizard(server: str, idx: int, steps: list, phase: str,
                  *, completion_url: str | None = None,
                  completion_label: str | None = None,
                  current_step_phase: str | None = None):
    # ... build HTML content ...

    # Smart template selection
    if not request.headers.get("HX-Request"):
        page = "wizard/frame.html"        # Initial load
    else:
        page = "wizard/_content.html"     # HTMX swap

    response = render_template(
        page,
        body_html=html,
        idx=idx,
        max_idx=len(steps) - 1,
        server_type=server,
        phase=phase,                      # NEW: Phase context
        step_phase=display_phase,         # NEW: Current step phase
        completion_url=completion_url,    # NEW: Completion redirect
        completion_label=completion_label # NEW: Completion button text
    )

    # Add headers for HTMX requests
    if request.headers.get("HX-Request"):
        resp = make_response(response)
        resp.headers['X-Wizard-Idx'] = str(idx)
        resp.headers['X-Require-Interaction'] = 'true' | 'false'
        resp.headers['X-Wizard-Step-Phase'] = display_phase or ''  # NEW
        return resp

    return response
```

--------------------------------

### Activity State Initialization and Parameter Building

Source: https://github.com/wizarrrr/wizarr/blob/main/app/activity/templates/activity/dashboard.html

Initializes a global activity state object and builds URL query parameters for filtering and sorting activity data. The state tracks UI details like open panels and pending refreshes, while the parameter builder reads filter inputs and sort order to construct the request.

```JavaScript
if (typeof window.ensureActivityState !== 'function') {
  window.ensureActivityState = function ensureActivityState() {
    if (!window.wizarrActivityState) {
      window.wizarrActivityState = {
        detailOpen: false,
        pendingRefresh: false,
        summaryTimer: null,
        lastSummary: null,
        summaryInFlight: false,
      };
    }
    return window.wizarrActivityState;
  };
}

function buildActivityParams(extra = {}) {
  const params = new URLSearchParams();
  const searchInput = document.getElementById('simple-search') || document.getElementById('user-search');
  const userName = (searchInput?.value || '').trim();
  const serverFilter = document.getElementById('server-filter')?.value;
  const mediaTypeFilter = document.getElementById('media-type-filter')?.value;
  const sortOrder = document.getElementById('sort-order')?.value;

  if (userName) params.set('user_name', userName);
  if (serverFilter) params.set('server_id', serverFilter);
  if (mediaTypeFilter) params.set('media_type', mediaTypeFilter);
  if (sortOrder) {
    const [sortBy, sortDirection] = sortOrder.split(':');
    if (sortBy) params.set('sort_by', sortBy);
    if (sortDirection) params.set('sort_direction', sortDirection);
  }
  if (typeof extra.page !== 'undefined') {
    params.set('page', extra.page);
  }
  if (typeof extra.limit !== 'undefined') {
    params.set('limit', extra.limit);
  }
  return params;
}
```

--------------------------------

### Test LDAP Connection with ldapsearch

Source: https://github.com/wizarrrr/wizarr/blob/main/docs/using-wizarr/ldap-authentication.md

Run this from the Wizarr container to test LDAP connectivity when the 'Cannot connect to LDAP server' error occurs.

```bash
docker exec wizarr ldapsearch -x -H ldap://lldap:3890 -b "dc=example,dc=com"
```

--------------------------------

### Wizard Controller JavaScript

Source: https://github.com/wizarrrr/wizarr/blob/main/app/templates/wizard/steps.html

This is the main wizard controller script that initializes the wizard, listens for HTMX swaps, and updates the UI based on server headers. It handles progress, navigation, and phase badges.

```javascript
/**
 * WIZARR WIZARD ARCHITECTURE
 * ==========================
 *
 * A modular, app-like wizard system with fixed UI chrome and smooth content transitions.
 *
 * STRUCTURE:
 * ----------
 * 1. Templates:
 *    - wizard/frame.html → Full page wrapper (initial load only)
 *    - wizard/steps.html → Wrapper with UI chrome (progress, buttons)
 *    - wizard/_content.html → Content-only partial (HTMX swaps)
 *
 * 2. Request Flow:
 *    - Initial load: Returns frame.html → includes steps.html → includes _content.html
 *    - HTMX request: Returns _content.html ONLY (no UI chrome duplication)
 *
 * 3. State Management:
 *    - Server sends headers: X-Wizard-Idx, X-Require-Interaction, X-Wizard-Step-Phase
 *    - Client updates: Progress bars, button URLs, button visibility, phase badges
 *    - Wrapper stores:
 *      - data-current-idx: Current wizard step index (int, 0-based)
 *      - data-max-idx: Maximum wizard step index (int)
 *      - data-server-type: Type of server being configured (string, e.g., "plex", "jellyfin")
 *      - data-phase: Current wizard phase (string, "pre" or "post")
 *      - data-step-phase: Current step phase (string, "pre" or "post" for pre-invite/post-invite)
 *    These attributes are updated by the server and client-side JS to synchronize UI state,
 *    drive progress bar, navigation button logic, and ensure correct HTMX swaps.
 *
 * 4. Mobile Features:
 *    - Fixed progress bar at top (no scroll)
 *    - Fixed navigation buttons at bottom (circular, gradient)
 *    - Swipe gestures (left=next, right=prev)
 *    - Content-only scrolling with smooth animations
 *
 * IMPORTANT:
 * ----------
 * - NEVER swap the wrapper (causes UI duplication)
 * - ONLY swap #wizard-content
 * - Progress/buttons update via JavaScript, not DOM replacement
 */
// Modern wizard controller
const WizardController = {
    wrapper: null,
    isInitialized: false,
    init() {
        // Prevent double initialization
        if (this.isInitialized) return;
        this.wrapper = document.getElementById('wizard-wrapper');
        if (!this.wrapper) {
            console.error('Wizard wrapper not found');
            return;
        }
        // Listen for content swaps
        document.body.addEventListener('htmx:afterSwap', (evt) => {
            if (evt.detail.target.id === 'wizard-content') {
                this.updateUI(evt.detail.xhr);
            }
        });
        this.isInitialized = true;
        console.log('WizardController initialized');
        this.updatePhaseBadges(this.getStepPhase());
    },
    getCurrentIdx() {
        return parseInt(this.wrapper.dataset.currentIdx);
    },
    getMaxIdx() {
        return parseInt(this.wrapper.dataset.maxIdx);
    },
    getServerType() {
        return this.wrapper.dataset.serverType;
    },
    getPhase() {
        return this.wrapper.dataset.phase || '';
    },
    getStepPhase() {
        return this.wrapper.dataset.stepPhase || '';
    },
    getCompletionUrl() {
        return this.wrapper.dataset.completionUrl || '';
    },
    getCompletionLabel() {
        return this.wrapper.dataset.completionLabel || '';
    },
    getDefaultNextLabel() {
        return this.wrapper.dataset.nextLabel || 'Next';
    },
    updateUI(xhr) {
        if (!xhr) {
            console.error('No XHR object provided');
            return;
        }
        const hxRedirect = xhr.getResponseHeader('HX-Redirect');
        if (hxRedirect) {
            // HTMX will handle navigation; skip local state updates to avoid errors.
            return;
        }
        const newIdx = parseInt(xhr.getResponseHeader('X-Wizard-Idx'));
        const requireInteraction = xhr.getResponseHeader('X-Require-Interaction') === 'true';
        const maxIdx = this.getMaxIdx();
        const serverType = this.getServerType();
        const newStepPhase = xhr.getResponseHeader('X-Wizard-Step-Phase');
        // Validation
        if (isNaN(newIdx) || isNaN(maxIdx)) {
            console.error('Invalid index values:', { newIdx, maxIdx });
            return;
        }
        // ... (rest of the method)
    }
};
```

--------------------------------

### Caddy path-based reverse proxy for wizarr with response replacement

Source: https://github.com/wizarrrr/wizarr/blob/main/docs/getting-started/reverse-proxy.md

This Caddy configuration serves wizarr under a path (`/wizarr`) on an existing domain. It requires the `replace-response` module to rewrite URLs and paths. It redirects `/wizarr` to `/wizarr/admin`, replaces various URL patterns, and proxies to the wizarr backend on port 5690 while keeping the main service on port 5055.

```caddy
plex.example.com {
    redir /wizarr /wizarr/admin

    handle_path /wizarr/* {
        replace {
            "href=\"/"      "href=\"/wizarr/"
            "action=\"/"    "action=\"/wizarr/"
            "\"/static"       "\"/wizarr/static"
            "hx-post=\"/"   "hx-post=\"/wizarr/"
            "hx-get=\"/"    "hx-get=\"/wizarr/"
            "scan=\"/"      "href=\"/wizarr/"
            "/scan"         "/wizarr/scan"
            # include in join code path copy
            "navigator.clipboard.writeText(url + \"/j/\" + invite_code);" "navigator.clipboard.writeText(url + \"/wizarr/j/\" + invite_code);"
        }
        
        # Your wizarr backend
        reverse_proxy http://127.0.0.1:5690
    }
    # Your main service that you want at /
    reverse_proxy http://127.0.0.1:5055
}
```

--------------------------------

### Client state storage in #wizard-wrapper element

Source: https://github.com/wizarrrr/wizarr/blob/main/WIZARD_ARCHITECTURE.md

HTML element with data attributes storing wizard state: current index, max index, server type, phase, step phase, completion URL, and completion label.

```html
<div id="wizard-wrapper"
     data-current-idx="0"
     data-max-idx="5"
     data-server-type="plex"
     data-phase="pre|post|preview"
     data-step-phase="pre|post"
     data-completion-url="/pre-wizard/complete"
     data-completion-label="Continue to Invite">
```

--------------------------------

### Run recovery tool in Docker

Source: https://github.com/wizarrrr/wizarr/blob/main/docs/using-wizarr/password-passkey-recovery.md

Find the container name and run the recovery tool inside a Docker container.

```bash
docker ps
```

```bash
docker exec -it <container_name> uv run recovery_tool.py
```

--------------------------------

### Session Management Methods for Pre-Invite Phase

Source: https://github.com/wizarrrr/wizarr/blob/main/WIZARD_ARCHITECTURE.md

Retrieve, validate, and mark the pre-wizard phase complete using InviteCodeManager methods. These methods manage the invite code session data during the pre-invite phase.

```python
InviteCodeManager.get_invite_code()           # Retrieve invite code
InviteCodeManager.validate_invite_code(code)  # Validate invite code
InviteCodeManager.mark_pre_wizard_complete()  # Mark phase complete
```

--------------------------------

### Bundle Export JSON Format

Source: https://github.com/wizarrrr/wizarr/blob/main/app/templates/settings/wizard/import_form.html

Expected JSON format for exporting bundles. The object contains name, description, and an array of steps.

```json
{
                                                  "name": "Bundle Name",
                                                  "description": "Bundle description",
                                                  "steps": [
                                                    {
                                                      "title": "Step Title",
                                                      "markdown": "Step content in markdown",
                                                      "order": 1
                                                    },
                                                    ...
                                                  ]
                                                }
```

--------------------------------

### Dynamic option visibility based on server type

Source: https://github.com/wizarrrr/wizarr/blob/main/app/templates/modals/create-server.html

JavaScript function that updates the displayed options when the server type changes. It shows media server options for most types, hides live TV for Audiobookshelf and Komga, shows mobile uploads only for Plex and Emby, and toggles RomM-specific fields.

```javascript
function closeModal() {
    document.getElementById('create-server-modal').innerHTML = '';
}

function updateOptions() {
    const type = document.getElementById('server_type').value;
    // Show universal media server options for Plex, Jellyfin, Emby, Audiobookshelf, and Komga
    const showMediaOptions = ['plex', 'jellyfin', 'emby', 'audiobookshelf', 'komga'].includes(type);
    document.getElementById('media-server-options').style.display = showMediaOptions ? 'block' : 'none';
    // Hide "Allow Live TV" for Audiobookshelf and Komga since they don't support Live TV
    const allowLiveTvOption = document.getElementById('allow-live-tv-option');
    if (allowLiveTvOption) {
        allowLiveTvOption.style.display = ['audiobookshelf', 'komga'].includes(type) ? 'none' : 'block';
    }
    // Hide "Allow Mobile Uploads" for Audiobookshelf, Jellyfin, and Komga since they don't support mobile uploads
    const allowMobileUploadsOption = document.getElementById('allow-mobile-uploads-option');
    if (allowMobileUploadsOption) {
        allowMobileUploadsOption.style.display = ['plex', 'emby'].includes(type) ? 'block' : 'none';
    }
    document.getElementById('romm-options').style.display = type === 'romm' ? 'block' : 'none';
    document.getElementById('api-key-div').style.display = type === 'romm' ? 'none' : 'block';
}

document.getElementById('server_type').addEventListener('change', updateOptions);
updateOptions();
```

--------------------------------

### YAML Front Matter for Step Files

Source: https://github.com/wizarrrr/wizarr/blob/main/docs/using-wizarr/customise-steps.md

Defines the required front matter for each step file. The 'title' is the step name, and 'require' indicates if the step is mandatory.

```yaml
---
title: Download the App
require: true
---

# Your content here
```

--------------------------------

### Session Cleanup for Post-Invite Phase

Source: https://github.com/wizarrrr/wizarr/blob/main/WIZARD_ARCHITECTURE.md

Clear invite-related data and wizard session flags after the post-invite phase completes. This cleanup ensures no stale session data remains.

```python
InviteCodeManager.clear_invite_data()  # Clear invite-related data
session.pop("wizard_access", None)     # Clear wizard access flag
session.pop("wizard_server_order", None)
session.pop("wizard_bundle_id", None)
```

--------------------------------

### Mock State Management

Source: https://github.com/wizarrrr/wizarr/blob/main/tests/README.md

State management for mocks: retrieve the mock state, check created users, and reset for clean tests.

```python
from tests.mocks import get_mock_state

# Check created users
state = get_mock_state()
print(f"Created {len(state.users)} users")

# Reset for clean tests
state.reset()
```

--------------------------------

### Jellyfin Mock API Behavior

Source: https://github.com/wizarrrr/wizarr/blob/main/tests/README.md

Mock API behavior for Jellyfin: success response, library assignment, and error simulation.

```python
# Success response
{
    "Id": "user-uuid",
    "Name": "username", 
    "Primary": "email@example.com",
    "Policy": {"EnableDownloads": True}
}

# Library assignment
client._set_specific_folders(user_id, ["lib1", "lib2"])

# Error simulation
simulate_user_creation_failure(["problematic_user"])
```
Tokens:
Raw