Proyecto LCX Dispatcharr multicuenta

.dockerignore

@@ -0,0 +1,33 @@
+**/__pycache__
+**/.venv
+**/venv
+**/.classpath
+**/.dockerignore
+**/.env
+**/.git
+**/.gitignore
+**/.project
+**/.settings
+**/.toolstarget
+**/.vs
+**/.vscode
+**/.history
+**/media
+**/models
+**/static
+**/*.*proj.user
+**/*.dbmdl
+**/*.jfm
+**/bin
+**/charts
+**/docker-compose*
+**/compose*
+**/Dockerfile*
+**/node_modules
+**/npm-debug.log
+**/obj
+**/secrets.dev.yaml
+**/values.dev.yaml
+LICENSE
+data/
+docker/data/

.env

@@ -0,0 +1,9 @@
+DATABASE_URL=postgresql://dispatcharr_usr:N9Ol57j5ENUa1@localhost:5432/dispatcharr_db
+POSTGRES_DB=dispatcharr_db
+POSTGRES_USER=dispatcharr_usr
+POSTGRES_PASSWORD=N9Ol57j5ENUa1
+POSTGRES_HOST=localhost
+CELERY_BROKER_URL=redis://localhost:6379/0
+DJANGO_SECRET_KEY=knZbsSxqlGozLGvJSfx02uHq1zOXhDuq8Vp34u4o8vyB71OoZU
+DISPATCHARR_VOD_CATALOG_ACCOUNT_ID=10
+DISPATCHARR_VOD_PLAYBACK_ACCOUNT_IDS=10,11,12

.gitattributes

@@ -0,0 +1,20 @@
+# Auto detect text files and perform LF normalization
+* text=auto
+
+# Explicitly declare text files that should always be normalized
+*.py text
+*.js text
+*.jsx text
+*.css text
+*.html text
+*.md text
+
+# Declare files that will always have specific line endings
+*.bat text eol=crlf
+*.sh text eol=lf
+
+# Denote all files that are truly binary and should not be modified
+*.png binary
+*.jpg binary
+*.gif binary
+*.ico binary

.github/FUNDING.yml

@@ -0,0 +1,15 @@
+# These are supported funding model platforms
+
+github: # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
+patreon: # Replace with a single Patreon username
+open_collective: dispatcharr # Replace with a single Open Collective username
+ko_fi: # Replace with a single Ko-fi username
+tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+liberapay: # Replace with a single Liberapay username
+issuehunt: # Replace with a single IssueHunt username
+lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
+polar: # Replace with a single Polar username
+buy_me_a_coffee: # Replace with a single Buy Me a Coffee username
+thanks_dev: # Replace with a single thanks.dev username
+custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,64 @@
+name: Bug Report
+description: I have an issue with Dispatcharr
+title: "[Bug]: "
+labels: ["Triage"]
+type: "Bug"
+projects: []
+assignees: []
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Please make sure you search for similar issues before submitting. Thank you for your bug report!
+  - type: textarea
+    id: describe-the-bug
+    attributes:
+      label: Describe the bug
+      description: Make sure to attach screenshots if possible!
+      placeholder: Tell us what you see!
+      value: "A clear and concise description of what the bug is. What did you expect to happen?"
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: How can we recreate this bug?
+      description: Be detailed!
+      placeholder: Tell us what you see!
+      value: "1. Go to '...' 2. Click on '....' 3. Scroll down to '....' 4. See error"
+    validations:
+      required: true
+  - type: input
+    id: dispatcharr-version
+    attributes:
+      label: Dispatcharr Version
+      description: What version of Dispatcharr are you running?
+      placeholder: Located bottom left of main screen
+    validations:
+      required: true
+  - type: input
+    id: docker-version
+    attributes:
+      label: Docker Version
+      description: What version of Docker are you running?
+      placeholder: docker --version
+    validations:
+      required: true
+  - type: textarea
+    id: docker-compose
+    attributes:
+      label: What's in your Docker Compose file?
+      description: Please share your docker-compose.yml file
+      placeholder: Tell us what you see!
+      value: "If not using Docker Compose just put not using."
+    validations:
+      required: true
+  - type: textarea
+    id: client-info
+    attributes:
+      label: Client Information
+      description: What are you using the view the streams from Dispatcharr
+      placeholder: Tell us what you see!
+      value: "Device, App, Versions for both, etc..."
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: false

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,39 @@
+name: Feature request
+description: I want to suggest a new feature for Dispatcharr
+title: "[Feature]: "
+labels: ["Triage"]
+type: "Feature"
+projects: []
+assignees: []
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for helping to make Dispatcharr better!
+  - type: textarea
+    id: describe-problem
+    attributes:
+      label: Is your feature request related to a problem?
+      description: Make sure to attach screenshots if possible!
+      placeholder: Tell us what you see!
+      value: "A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]"
+    validations:
+      required: true
+  - type: textarea
+    id: describe-solution
+    attributes:
+      label: Describe the solution you'd like
+      description: A clear and concise description of what you want to happen.
+      placeholder: Tell us what you see!
+      value: "Describe here."
+    validations:
+      required: true
+  - type: textarea
+    id: extras
+    attributes:
+      label: Additional context
+      description: Anything else you want to add?
+      placeholder: Tell us what you see!
+      value: "Nothing Extra"
+    validations:
+      required: true

.github/pull_request_template.md

@@ -0,0 +1,29 @@
+## Description
+
+<!-- What does this PR do? Be specific. -->
+
+## Related Issue
+
+<!-- Non-trivial changes should have a linked issue. If this is a small/obvious fix, you may leave this blank. -->
+
+Closes #
+
+## How was it tested?
+
+<!-- What did you actually run to verify this works? Be specific — "it works" is not sufficient. -->
+
+## Checklist
+
+Please check every item before marking this PR as ready for review. Unchecked items will be flagged during review.
+
+- [ ] I have read the [CONTRIBUTING.md](../blob/dev/CONTRIBUTING.md) in full
+- [ ] I agree to the [Contributor License Agreement](../blob/dev/CONTRIBUTING.md#contributor-license-agreement)
+- [ ] I understand — line by line — every change in this PR and can explain it if asked
+- [ ] This PR targets the `dev` branch
+- [ ] Backend: migrations are included if any models were changed
+- [ ] Backend: new API endpoints appear correctly in the OpenAPI schema
+- [ ] Frontend: ESLint and Prettier pass cleanly (`npm run lint`, `npm run format`)
+- [ ] Tests are included for new functionality
+- [ ] Existing tests still pass
+- [ ] No `console.log`, `print()`, debug statements, or commented-out code is left in the diff
+- [ ] I have not reformatted or refactored code outside the scope of this change

.github/workflows/base-image.yml

@@ -0,0 +1,250 @@
+name: Base Image Build
+
+on:
+  push:
+    branches: [main, dev]
+    paths:
+      - 'docker/DispatcharrBase'
+      - '.github/workflows/base-image.yml'
+      - 'pyproject.toml'
+  pull_request:
+    branches: [main, dev]
+    paths:
+      - 'docker/DispatcharrBase'
+      - '.github/workflows/base-image.yml'
+      - 'pyproject.toml'
+  workflow_dispatch: # Allow manual triggering
+
+permissions:
+  contents: write # For managing releases and pushing tags
+  packages: write # For publishing to GitHub Container Registry
+
+jobs:
+  prepare:
+    runs-on: ubuntu-24.04
+    outputs:
+      repo_owner: ${{ steps.meta.outputs.repo_owner }}
+      repo_name: ${{ steps.meta.outputs.repo_name }}
+      branch_tag: ${{ steps.meta.outputs.branch_tag }}
+      timestamp: ${{ steps.timestamp.outputs.timestamp }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Generate timestamp for build
+        id: timestamp
+        run: |
+          TIMESTAMP=$(date -u +'%Y%m%d%H%M%S')
+          echo "timestamp=${TIMESTAMP}" >> $GITHUB_OUTPUT
+
+      - name: Set repository and image metadata
+        id: meta
+        run: |
+          # Get lowercase repository owner
+          REPO_OWNER=$(echo "${{ github.repository_owner }}" | tr '[:upper:]' '[:lower:]')
+          echo "repo_owner=${REPO_OWNER}" >> $GITHUB_OUTPUT
+
+          # Get repository name
+          REPO_NAME=$(echo "${{ github.repository }}" | cut -d '/' -f 2 | tr '[:upper:]' '[:lower:]')
+          echo "repo_name=${REPO_NAME}" >> $GITHUB_OUTPUT
+
+          # Determine branch name
+          if [[ "${{ github.ref }}" == "refs/heads/main" ]]; then
+            echo "branch_tag=base" >> $GITHUB_OUTPUT
+          elif [[ "${{ github.ref }}" == "refs/heads/dev" ]]; then
+            echo "branch_tag=base-dev" >> $GITHUB_OUTPUT
+          else
+            # For other branches, use the branch name
+            BRANCH=$(echo "${{ github.ref }}" | sed 's/refs\/heads\///' | sed 's/[^a-zA-Z0-9]/-/g')
+            echo "branch_tag=base-${BRANCH}" >> $GITHUB_OUTPUT
+          fi
+
+  docker:
+    needs: [prepare]
+    strategy:
+      fail-fast: false
+      matrix:
+        platform: [amd64, arm64]
+        include:
+          - platform: amd64
+            runner: ubuntu-24.04
+          - platform: arm64
+            runner: ubuntu-24.04-arm
+    runs-on: ${{ matrix.runner }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Configure Git
+        run: |
+          git config user.name "GitHub Actions"
+          git config user.email "actions@github.com"
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Login to Docker Hub
+        uses: docker/login-action@v4
+        with:
+          registry: docker.io
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Extract metadata for Docker
+        id: meta
+        uses: docker/metadata-action@v6
+        with:
+          images: |
+            ghcr.io/${{ needs.prepare.outputs.repo_owner }}/${{ needs.prepare.outputs.repo_name }}
+            docker.io/${{ secrets.DOCKERHUB_ORGANIZATION }}/${{ needs.prepare.outputs.repo_name }}
+          labels: |
+            org.opencontainers.image.title=${{ needs.prepare.outputs.repo_name }}
+            org.opencontainers.image.description=Your ultimate IPTV & stream Management companion.
+            org.opencontainers.image.url=https://github.com/${{ github.repository }}
+            org.opencontainers.image.source=https://github.com/${{ github.repository }}
+            org.opencontainers.image.version=${{ needs.prepare.outputs.branch_tag }}-${{ needs.prepare.outputs.timestamp }}
+            org.opencontainers.image.created=${{ needs.prepare.outputs.timestamp }}
+            org.opencontainers.image.revision=${{ github.sha }}
+            org.opencontainers.image.licenses=See repository
+            org.opencontainers.image.documentation=https://dispatcharr.github.io/Dispatcharr-Docs/
+            org.opencontainers.image.vendor=${{ needs.prepare.outputs.repo_owner }}
+            org.opencontainers.image.authors=${{ github.actor }}
+            maintainer=${{ github.actor }}
+            build_version=DispatcharrBase version: ${{ needs.prepare.outputs.branch_tag }}-${{ needs.prepare.outputs.timestamp }}
+
+      - name: Build and push Docker base image
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          file: ./docker/DispatcharrBase
+          push: ${{ github.event_name != 'pull_request' }}
+          platforms: linux/${{ matrix.platform }}
+          tags: |
+            ghcr.io/${{ needs.prepare.outputs.repo_owner }}/${{ needs.prepare.outputs.repo_name }}:${{ needs.prepare.outputs.branch_tag }}-${{ matrix.platform }}
+            ghcr.io/${{ needs.prepare.outputs.repo_owner }}/${{ needs.prepare.outputs.repo_name }}:${{ needs.prepare.outputs.branch_tag }}-${{ needs.prepare.outputs.timestamp }}-${{ matrix.platform }}
+            docker.io/${{ secrets.DOCKERHUB_ORGANIZATION }}/${{ needs.prepare.outputs.repo_name }}:${{ needs.prepare.outputs.branch_tag }}-${{ matrix.platform }}
+            docker.io/${{ secrets.DOCKERHUB_ORGANIZATION }}/${{ needs.prepare.outputs.repo_name }}:${{ needs.prepare.outputs.branch_tag }}-${{ needs.prepare.outputs.timestamp }}-${{ matrix.platform }}
+          labels: ${{ steps.meta.outputs.labels }}
+          build-args: |
+            REPO_OWNER=${{ needs.prepare.outputs.repo_owner }}
+            REPO_NAME=${{ needs.prepare.outputs.repo_name }}
+            BRANCH=${{ github.ref_name }}
+            REPO_URL=https://github.com/${{ github.repository }}
+            TIMESTAMP=${{ needs.prepare.outputs.timestamp }}
+
+  create-manifest:
+    needs: [prepare, docker]
+    runs-on: ubuntu-24.04
+    if: ${{ github.event_name != 'pull_request' }}
+    steps:
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Login to Docker Hub
+        uses: docker/login-action@v4
+        with:
+          registry: docker.io
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Create multi-arch manifest tags
+        run: |
+          set -euo pipefail
+          OWNER=${{ needs.prepare.outputs.repo_owner }}
+          REPO=${{ needs.prepare.outputs.repo_name }}
+          BRANCH_TAG=${{ needs.prepare.outputs.branch_tag }}
+          TIMESTAMP=${{ needs.prepare.outputs.timestamp }}
+
+          echo "Creating multi-arch manifest for ${OWNER}/${REPO}"
+
+          # GitHub Container Registry manifests
+          # branch tag (e.g. base or base-dev)
+          docker buildx imagetools create \
+            --annotation "index:org.opencontainers.image.title=${{ needs.prepare.outputs.repo_name }}" \
+            --annotation "index:org.opencontainers.image.description=Your ultimate IPTV & stream Management companion." \
+            --annotation "index:org.opencontainers.image.url=https://github.com/${{ github.repository }}" \
+            --annotation "index:org.opencontainers.image.source=https://github.com/${{ github.repository }}" \
+            --annotation "index:org.opencontainers.image.version=${BRANCH_TAG}-${TIMESTAMP}" \
+            --annotation "index:org.opencontainers.image.created=${TIMESTAMP}" \
+            --annotation "index:org.opencontainers.image.revision=${{ github.sha }}" \
+            --annotation "index:org.opencontainers.image.licenses=See repository" \
+            --annotation "index:org.opencontainers.image.documentation=https://dispatcharr.github.io/Dispatcharr-Docs/" \
+            --annotation "index:org.opencontainers.image.vendor=${OWNER}" \
+            --annotation "index:org.opencontainers.image.authors=${{ github.actor }}" \
+            --annotation "index:maintainer=${{ github.actor }}" \
+            --annotation "index:build_version=DispatcharrBase version: ${BRANCH_TAG}-${TIMESTAMP}" \
+            --tag ghcr.io/${OWNER}/${REPO}:${BRANCH_TAG} \
+            ghcr.io/${OWNER}/${REPO}:${BRANCH_TAG}-amd64 ghcr.io/${OWNER}/${REPO}:${BRANCH_TAG}-arm64
+
+          # branch + timestamp tag
+          docker buildx imagetools create \
+            --annotation "index:org.opencontainers.image.title=${{ needs.prepare.outputs.repo_name }}" \
+            --annotation "index:org.opencontainers.image.description=Your ultimate IPTV & stream Management companion." \
+            --annotation "index:org.opencontainers.image.url=https://github.com/${{ github.repository }}" \
+            --annotation "index:org.opencontainers.image.source=https://github.com/${{ github.repository }}" \
+            --annotation "index:org.opencontainers.image.version=${BRANCH_TAG}-${TIMESTAMP}" \
+            --annotation "index:org.opencontainers.image.created=${TIMESTAMP}" \
+            --annotation "index:org.opencontainers.image.revision=${{ github.sha }}" \
+            --annotation "index:org.opencontainers.image.licenses=See repository" \
+            --annotation "index:org.opencontainers.image.documentation=https://dispatcharr.github.io/Dispatcharr-Docs/" \
+            --annotation "index:org.opencontainers.image.vendor=${OWNER}" \
+            --annotation "index:org.opencontainers.image.authors=${{ github.actor }}" \
+            --annotation "index:maintainer=${{ github.actor }}" \
+            --annotation "index:build_version=DispatcharrBase version: ${BRANCH_TAG}-${TIMESTAMP}" \
+            --tag ghcr.io/${OWNER}/${REPO}:${BRANCH_TAG}-${TIMESTAMP} \
+            ghcr.io/${OWNER}/${REPO}:${BRANCH_TAG}-${TIMESTAMP}-amd64 ghcr.io/${OWNER}/${REPO}:${BRANCH_TAG}-${TIMESTAMP}-arm64
+
+          # Docker Hub manifests
+          # branch tag (e.g. base or base-dev)
+          docker buildx imagetools create \
+            --annotation "index:org.opencontainers.image.title=${{ needs.prepare.outputs.repo_name }}" \
+            --annotation "index:org.opencontainers.image.description=Your ultimate IPTV & stream Management companion." \
+            --annotation "index:org.opencontainers.image.url=https://github.com/${{ github.repository }}" \
+            --annotation "index:org.opencontainers.image.source=https://github.com/${{ github.repository }}" \
+            --annotation "index:org.opencontainers.image.version=${BRANCH_TAG}-${TIMESTAMP}" \
+            --annotation "index:org.opencontainers.image.created=${TIMESTAMP}" \
+            --annotation "index:org.opencontainers.image.revision=${{ github.sha }}" \
+            --annotation "index:org.opencontainers.image.licenses=See repository" \
+            --annotation "index:org.opencontainers.image.documentation=https://dispatcharr.github.io/Dispatcharr-Docs/" \
+            --annotation "index:org.opencontainers.image.vendor=${OWNER}" \
+            --annotation "index:org.opencontainers.image.authors=${{ github.actor }}" \
+            --annotation "index:maintainer=${{ github.actor }}" \
+            --annotation "index:build_version=DispatcharrBase version: ${BRANCH_TAG}-${TIMESTAMP}" \
+            --tag docker.io/${{ secrets.DOCKERHUB_ORGANIZATION }}/${REPO}:${BRANCH_TAG} \
+            docker.io/${{ secrets.DOCKERHUB_ORGANIZATION }}/${REPO}:${BRANCH_TAG}-amd64 docker.io/${{ secrets.DOCKERHUB_ORGANIZATION }}/${REPO}:${BRANCH_TAG}-arm64
+
+          # branch + timestamp tag
+          docker buildx imagetools create \
+            --annotation "index:org.opencontainers.image.title=${{ needs.prepare.outputs.repo_name }}" \
+            --annotation "index:org.opencontainers.image.description=Your ultimate IPTV & stream Management companion." \
+            --annotation "index:org.opencontainers.image.url=https://github.com/${{ github.repository }}" \
+            --annotation "index:org.opencontainers.image.source=https://github.com/${{ github.repository }}" \
+            --annotation "index:org.opencontainers.image.version=${BRANCH_TAG}-${TIMESTAMP}" \
+            --annotation "index:org.opencontainers.image.created=${TIMESTAMP}" \
+            --annotation "index:org.opencontainers.image.revision=${{ github.sha }}" \
+            --annotation "index:org.opencontainers.image.licenses=See repository" \
+            --annotation "index:org.opencontainers.image.documentation=https://dispatcharr.github.io/Dispatcharr-Docs/" \
+            --annotation "index:org.opencontainers.image.vendor=${OWNER}" \
+            --annotation "index:org.opencontainers.image.authors=${{ github.actor }}" \
+            --annotation "index:maintainer=${{ github.actor }}" \
+            --annotation "index:build_version=DispatcharrBase version: ${BRANCH_TAG}-${TIMESTAMP}" \
+            --tag docker.io/${{ secrets.DOCKERHUB_ORGANIZATION }}/${REPO}:${BRANCH_TAG}-${TIMESTAMP} \
+            docker.io/${{ secrets.DOCKERHUB_ORGANIZATION }}/${REPO}:${BRANCH_TAG}-${TIMESTAMP}-amd64 docker.io/${{ secrets.DOCKERHUB_ORGANIZATION }}/${REPO}:${BRANCH_TAG}-${TIMESTAMP}-arm64

.github/workflows/ci.yml

@@ -0,0 +1,243 @@
+name: CI Pipeline
+
+on:
+  push:
+    branches: [dev]
+    paths-ignore:
+      - '**.md'
+  pull_request:
+    branches: [dev]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  packages: write
+
+jobs:
+  prepare:
+    runs-on: ubuntu-24.04
+    # compute a single timestamp, version, and repo metadata for the entire workflow
+    outputs:
+      repo_owner: ${{ steps.meta.outputs.repo_owner }}
+      repo_name: ${{ steps.meta.outputs.repo_name }}
+      branch_tag: ${{ steps.meta.outputs.branch_tag }}
+      version: ${{ steps.version.outputs.version }}
+      timestamp: ${{ steps.timestamp.outputs.timestamp }}
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Generate timestamp for build
+        id: timestamp
+        run: |
+          TIMESTAMP=$(date -u +'%Y%m%d%H%M%S')
+          echo "timestamp=${TIMESTAMP}" >> $GITHUB_OUTPUT
+
+      - name: Extract version info
+        id: version
+        run: |
+          VERSION=$(python -c "import version; print(version.__version__)")
+          echo "version=${VERSION}" >> $GITHUB_OUTPUT
+
+      - name: Set repository and image metadata
+        id: meta
+        run: |
+          REPO_OWNER=$(echo "${{ github.repository_owner }}" | tr '[:upper:]' '[:lower:]')
+          echo "repo_owner=${REPO_OWNER}" >> $GITHUB_OUTPUT
+
+          REPO_NAME=$(echo "${{ github.repository }}" | cut -d '/' -f 2 | tr '[:upper:]' '[:lower:]')
+          echo "repo_name=${REPO_NAME}" >> $GITHUB_OUTPUT
+
+          if [[ "${{ github.ref }}" == "refs/heads/main" ]]; then
+            echo "branch_tag=latest" >> $GITHUB_OUTPUT
+            echo "is_main=true" >> $GITHUB_OUTPUT
+          elif [[ "${{ github.ref }}" == "refs/heads/dev" ]]; then
+            echo "branch_tag=dev" >> $GITHUB_OUTPUT
+            echo "is_main=false" >> $GITHUB_OUTPUT
+          else
+            BRANCH=$(echo "${{ github.ref }}" | sed 's/refs\/heads\///' | sed 's/[^a-zA-Z0-9]/-/g')
+            echo "branch_tag=${BRANCH}" >> $GITHUB_OUTPUT
+            echo "is_main=false" >> $GITHUB_OUTPUT
+          fi
+
+          if [[ "${{ github.event.pull_request.head.repo.fork }}" == "true" ]]; then
+            echo "is_fork=true" >> $GITHUB_OUTPUT
+          else
+            echo "is_fork=false" >> $GITHUB_OUTPUT
+          fi
+
+  docker:
+    needs: [prepare]
+    strategy:
+      fail-fast: false
+      matrix:
+        platform: [amd64, arm64]
+        include:
+          - platform: amd64
+            runner: ubuntu-24.04
+          - platform: arm64
+            runner: ubuntu-24.04-arm
+    runs-on: ${{ matrix.runner }}
+    # no per-job outputs here; shared metadata comes from the `prepare` job
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Configure Git
+        run: |
+          git config user.name "GitHub Actions"
+          git config user.email "actions@github.com"
+
+      - name: Check if commit is from GitHub Actions
+        id: check_actor
+        run: |
+          if [[ "${{ github.actor }}" == "github-actions" ]]; then
+            echo "is_bot=true" >> $GITHUB_OUTPUT
+          else
+            echo "is_bot=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Login to Docker Hub
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@v4
+        with:
+          registry: docker.io
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Extract metadata for Docker
+        id: meta
+        uses: docker/metadata-action@v6
+        with:
+          images: |
+            ghcr.io/${{ needs.prepare.outputs.repo_owner }}/${{ needs.prepare.outputs.repo_name }}
+            docker.io/${{ secrets.DOCKERHUB_ORGANIZATION }}/${{ needs.prepare.outputs.repo_name }}
+          labels: |
+            org.opencontainers.image.title=${{ needs.prepare.outputs.repo_name }}
+            org.opencontainers.image.description=Your ultimate IPTV & stream Management companion.
+            org.opencontainers.image.url=https://github.com/${{ github.repository }}
+            org.opencontainers.image.source=https://github.com/${{ github.repository }}
+            org.opencontainers.image.version=${{ needs.prepare.outputs.version }}-${{ needs.prepare.outputs.timestamp }}
+            org.opencontainers.image.created=${{ needs.prepare.outputs.timestamp }}
+            org.opencontainers.image.revision=${{ github.sha }}
+            org.opencontainers.image.licenses=See repository
+            org.opencontainers.image.documentation=https://dispatcharr.github.io/Dispatcharr-Docs/
+            org.opencontainers.image.vendor=${{ needs.prepare.outputs.repo_owner }}
+            org.opencontainers.image.authors=${{ github.actor }}
+            maintainer=${{ github.actor }}
+            build_version=Dispatcharr version: ${{ needs.prepare.outputs.version }}-${{ needs.prepare.outputs.timestamp }}
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          push: ${{ github.event_name != 'pull_request' }}
+          # Build only the platform for this matrix job to avoid running amd64
+          # stages under qemu on an arm64 runner (and vice-versa). This makes
+          # the matrix runner's platform the one built by buildx.
+          platforms: linux/${{ matrix.platform }}
+          # push arch-specific tags from each matrix job (they will be combined
+          # into a multi-arch manifest in a follow-up job)
+          tags: |
+            ghcr.io/${{ needs.prepare.outputs.repo_owner }}/${{ needs.prepare.outputs.repo_name }}:${{ needs.prepare.outputs.branch_tag }}-${{ matrix.platform }}
+            ghcr.io/${{ needs.prepare.outputs.repo_owner }}/${{ needs.prepare.outputs.repo_name }}:${{ needs.prepare.outputs.version }}-${{ needs.prepare.outputs.timestamp }}-${{ matrix.platform }}
+            ${{ github.event_name != 'pull_request' && format('docker.io/{0}/{1}:{2}-{3}', secrets.DOCKERHUB_ORGANIZATION, needs.prepare.outputs.repo_name, needs.prepare.outputs.branch_tag, matrix.platform) || '' }}
+            ${{ github.event_name != 'pull_request' && format('docker.io/{0}/{1}:{2}-{3}-{4}', secrets.DOCKERHUB_ORGANIZATION, needs.prepare.outputs.repo_name, needs.prepare.outputs.version, needs.prepare.outputs.timestamp, matrix.platform) || '' }}
+          labels: ${{ steps.meta.outputs.labels }}
+          build-args: |
+            REPO_OWNER=${{ needs.prepare.outputs.repo_owner }}
+            REPO_NAME=${{ needs.prepare.outputs.repo_name }}
+            BASE_TAG=base
+            BRANCH=${{ github.ref_name }}
+            REPO_URL=https://github.com/${{ github.repository }}
+            TIMESTAMP=${{ needs.prepare.outputs.timestamp }}
+          file: ./docker/Dockerfile
+
+  create-manifest:
+    # wait for prepare and all matrix builds to finish
+    needs: [prepare, docker]
+    runs-on: ubuntu-24.04
+    if: ${{ github.event_name != 'pull_request' }}
+    steps:
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Login to Docker Hub
+        uses: docker/login-action@v4
+        with:
+          registry: docker.io
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Create multi-arch manifest tags
+        run: |
+          set -euo pipefail
+          OWNER=${{ needs.prepare.outputs.repo_owner }}
+          REPO=${{ needs.prepare.outputs.repo_name }}
+          BRANCH_TAG=${{ needs.prepare.outputs.branch_tag }}
+          VERSION=${{ needs.prepare.outputs.version }}
+          TIMESTAMP=${{ needs.prepare.outputs.timestamp }}
+
+          echo "Creating multi-arch manifest for ${OWNER}/${REPO}"
+
+          # ghcr.io: both the branch tag (e.g. dev) and the version+timestamp tag
+          # point to the same manifest by using multiple --tag flags in one call,
+          # which prevents orphaned untagged images on each new build
+          docker buildx imagetools create \
+            --annotation "index:org.opencontainers.image.title=${{ needs.prepare.outputs.repo_name }}" \
+            --annotation "index:org.opencontainers.image.description=Your ultimate IPTV & stream Management companion." \
+            --annotation "index:org.opencontainers.image.url=https://github.com/${{ github.repository }}" \
+            --annotation "index:org.opencontainers.image.source=https://github.com/${{ github.repository }}" \
+            --annotation "index:org.opencontainers.image.version=${VERSION}-${TIMESTAMP}" \
+            --annotation "index:org.opencontainers.image.created=${TIMESTAMP}" \
+            --annotation "index:org.opencontainers.image.revision=${{ github.sha }}" \
+            --annotation "index:org.opencontainers.image.licenses=See repository" \
+            --annotation "index:org.opencontainers.image.documentation=https://dispatcharr.github.io/Dispatcharr-Docs/" \
+            --annotation "index:org.opencontainers.image.vendor=${OWNER}" \
+            --annotation "index:org.opencontainers.image.authors=${{ github.actor }}" \
+            --annotation "index:maintainer=${{ github.actor }}" \
+            --annotation "index:build_version=Dispatcharr version: ${VERSION}-${TIMESTAMP}" \
+            --tag ghcr.io/${OWNER}/${REPO}:${BRANCH_TAG} \
+            --tag ghcr.io/${OWNER}/${REPO}:${VERSION}-${TIMESTAMP} \
+            ghcr.io/${OWNER}/${REPO}:${BRANCH_TAG}-amd64 ghcr.io/${OWNER}/${REPO}:${BRANCH_TAG}-arm64
+
+          # Docker Hub: same single call with both tags
+          docker buildx imagetools create \
+            --annotation "index:org.opencontainers.image.title=${{ needs.prepare.outputs.repo_name }}" \
+            --annotation "index:org.opencontainers.image.description=Your ultimate IPTV & stream Management companion." \
+            --annotation "index:org.opencontainers.image.url=https://github.com/${{ github.repository }}" \
+            --annotation "index:org.opencontainers.image.source=https://github.com/${{ github.repository }}" \
+            --annotation "index:org.opencontainers.image.version=${VERSION}-${TIMESTAMP}" \
+            --annotation "index:org.opencontainers.image.created=${TIMESTAMP}" \
+            --annotation "index:org.opencontainers.image.revision=${{ github.sha }}" \
+            --annotation "index:org.opencontainers.image.licenses=See repository" \
+            --annotation "index:org.opencontainers.image.documentation=https://dispatcharr.github.io/Dispatcharr-Docs/" \
+            --annotation "index:org.opencontainers.image.vendor=${OWNER}" \
+            --annotation "index:org.opencontainers.image.authors=${{ github.actor }}" \
+            --annotation "index:maintainer=${{ github.actor }}" \
+            --annotation "index:build_version=Dispatcharr version: ${VERSION}-${TIMESTAMP}" \
+            --tag docker.io/${{ secrets.DOCKERHUB_ORGANIZATION }}/${REPO}:${BRANCH_TAG} \
+            --tag docker.io/${{ secrets.DOCKERHUB_ORGANIZATION }}/${REPO}:${VERSION}-${TIMESTAMP} \
+            docker.io/${{ secrets.DOCKERHUB_ORGANIZATION }}/${REPO}:${BRANCH_TAG}-amd64 docker.io/${{ secrets.DOCKERHUB_ORGANIZATION }}/${REPO}:${BRANCH_TAG}-arm64

.github/workflows/docker-build.yml

@@ -0,0 +1,56 @@
+name: Build and Push Multi-Arch Docker Image
+
+on:
+  push:
+    branches:
+      - main
+      - dev
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Determine image tag and branch
+        id: set-tag-branch
+        run: |
+          if [[ "${{ github.ref }}" == "refs/heads/main" ]]; then
+            echo "TAG=latest" >> $GITHUB_ENV
+            echo "BRANCH=main" >> $GITHUB_ENV
+          elif [[ "${{ github.ref }}" == "refs/heads/dev" ]]; then
+            echo "TAG=dev" >> $GITHUB_ENV
+            echo "BRANCH=dev" >> $GITHUB_ENV
+          fi
+
+      - name: Convert repository name to lowercase
+        run: echo "REPO_NAME=$(echo '${{ github.repository }}' | tr '[:upper:]' '[:lower:]')" >> $GITHUB_ENV
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v7
+        with:
+          context: docker
+          file: docker/Dockerfile
+          push: true
+          platforms: linux/amd64,linux/arm64
+          build-args: |
+            BRANCH=${{ env.BRANCH }}
+            REPO_URL=https://github.com/${{ github.repository }}
+          tags: |
+            ghcr.io/${{ env.REPO_NAME }}:${{ env.TAG }}
+            ghcr.io/${{ env.REPO_NAME }}:${{ github.sha }}

.github/workflows/frontend-tests.yml

@@ -0,0 +1,41 @@
+name: Frontend Tests
+
+on:
+  push:
+    branches: [main, dev]
+    paths:
+      - 'frontend/**'
+      - '.github/workflows/frontend-tests.yml'
+  pull_request:
+    branches: [main, dev]
+    paths:
+      - 'frontend/**'
+      - '.github/workflows/frontend-tests.yml'
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    defaults:
+      run:
+        working-directory: ./frontend
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+          cache: 'npm'
+          cache-dependency-path: './frontend/package-lock.json'
+
+      - name: Install dependencies
+        run: npm ci
+
+      #      - name: Run linter
+      #        run: npm run lint
+
+      - name: Run tests
+        run: npm test

.github/workflows/release.yml

@@ -0,0 +1,237 @@
+name: Create Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version_type:
+        description: 'Type of version increment'
+        required: true
+        default: 'patch'
+        type: choice
+        options:
+          - major
+          - minor
+          - patch
+
+# Add explicit permissions for the workflow
+permissions:
+  contents: write # For managing releases and pushing tags
+  packages: write # For publishing to GitHub Container Registry
+
+jobs:
+  prepare:
+    runs-on: ubuntu-24.04
+    outputs:
+      new_version: ${{ steps.update_version.outputs.new_version }}
+      repo_owner: ${{ steps.meta.outputs.repo_owner }}
+      repo_name: ${{ steps.meta.outputs.repo_name }}
+      timestamp: ${{ steps.timestamp.outputs.timestamp }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Configure Git
+        run: |
+          git config user.name "GitHub Actions"
+          git config user.email "actions@github.com"
+
+      - name: Update Version
+        id: update_version
+        run: |
+          python scripts/bump_version.py ${{ github.event.inputs.version_type }}
+          NEW_VERSION=$(python -c "import version; print(f'{version.__version__}')")
+          echo "new_version=${NEW_VERSION}" >> $GITHUB_OUTPUT
+
+      - name: Update Changelog
+        run: |
+          python scripts/update_changelog.py ${{ steps.update_version.outputs.new_version }}
+
+      - name: Set repository metadata
+        id: meta
+        run: |
+          REPO_OWNER=$(echo "${{ github.repository_owner }}" | tr '[:upper:]' '[:lower:]')
+          echo "repo_owner=${REPO_OWNER}" >> $GITHUB_OUTPUT
+
+          REPO_NAME=$(echo "${{ github.repository }}" | cut -d '/' -f 2 | tr '[:upper:]' '[:lower:]')
+          echo "repo_name=${REPO_NAME}" >> $GITHUB_OUTPUT
+
+      - name: Generate timestamp for build
+        id: timestamp
+        run: |
+          TIMESTAMP=$(date -u +'%Y%m%d%H%M%S')
+          echo "timestamp=${TIMESTAMP}" >> $GITHUB_OUTPUT
+
+      - name: Commit and Tag
+        run: |
+          git add version.py CHANGELOG.md
+          git commit -m "Release v${{ steps.update_version.outputs.new_version }}"
+          git tag -a "v${{ steps.update_version.outputs.new_version }}" -m "Release v${{ steps.update_version.outputs.new_version }}"
+          git push origin main --tags
+
+  docker:
+    needs: [prepare]
+    strategy:
+      fail-fast: false
+      matrix:
+        platform: [amd64, arm64]
+        include:
+          - platform: amd64
+            runner: ubuntu-24.04
+          - platform: arm64
+            runner: ubuntu-24.04-arm
+    runs-on: ${{ matrix.runner }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+          ref: main
+
+      - name: Configure Git
+        run: |
+          git config user.name "GitHub Actions"
+          git config user.email "actions@github.com"
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Login to Docker Hub
+        uses: docker/login-action@v4
+        with:
+          registry: docker.io
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Extract metadata for Docker
+        id: meta
+        uses: docker/metadata-action@v6
+        with:
+          images: |
+            ghcr.io/${{ needs.prepare.outputs.repo_owner }}/${{ needs.prepare.outputs.repo_name }}
+            docker.io/${{ secrets.DOCKERHUB_ORGANIZATION }}/${{ needs.prepare.outputs.repo_name }}
+          labels: |
+            org.opencontainers.image.title=${{ needs.prepare.outputs.repo_name }}
+            org.opencontainers.image.description=Your ultimate IPTV & stream Management companion.
+            org.opencontainers.image.url=https://github.com/${{ github.repository }}
+            org.opencontainers.image.source=https://github.com/${{ github.repository }}
+            org.opencontainers.image.version=${{ needs.prepare.outputs.new_version }}
+            org.opencontainers.image.created=${{ needs.prepare.outputs.timestamp }}
+            org.opencontainers.image.revision=${{ github.sha }}
+            org.opencontainers.image.licenses=See repository
+            org.opencontainers.image.documentation=https://dispatcharr.github.io/Dispatcharr-Docs/
+            org.opencontainers.image.vendor=${{ needs.prepare.outputs.repo_owner }}
+            org.opencontainers.image.authors=${{ github.actor }}
+            maintainer=${{ github.actor }}
+            build_version=Dispatcharr version: ${{ needs.prepare.outputs.new_version }} Build date: ${{ needs.prepare.outputs.timestamp }}
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          push: true
+          platforms: linux/${{ matrix.platform }}
+          tags: |
+            ghcr.io/${{ needs.prepare.outputs.repo_owner }}/${{ needs.prepare.outputs.repo_name }}:latest-${{ matrix.platform }}
+            ghcr.io/${{ needs.prepare.outputs.repo_owner }}/${{ needs.prepare.outputs.repo_name }}:${{ needs.prepare.outputs.new_version }}-${{ matrix.platform }}
+            docker.io/${{ secrets.DOCKERHUB_ORGANIZATION }}/${{ needs.prepare.outputs.repo_name }}:latest-${{ matrix.platform }}
+            docker.io/${{ secrets.DOCKERHUB_ORGANIZATION }}/${{ needs.prepare.outputs.repo_name }}:${{ needs.prepare.outputs.new_version }}-${{ matrix.platform }}
+          labels: ${{ steps.meta.outputs.labels }}
+          build-args: |
+            REPO_OWNER=${{ needs.prepare.outputs.repo_owner }}
+            REPO_NAME=${{ needs.prepare.outputs.repo_name }}
+            BRANCH=${{ github.ref_name }}
+            REPO_URL=https://github.com/${{ github.repository }}
+          file: ./docker/Dockerfile
+
+  create-manifest:
+    needs: [prepare, docker]
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Login to Docker Hub
+        uses: docker/login-action@v4
+        with:
+          registry: docker.io
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Create multi-arch manifest tags
+        run: |
+          set -euo pipefail
+          OWNER=${{ needs.prepare.outputs.repo_owner }}
+          REPO=${{ needs.prepare.outputs.repo_name }}
+          VERSION=${{ needs.prepare.outputs.new_version }}
+          TIMESTAMP=${{ needs.prepare.outputs.timestamp }}
+
+          echo "Creating multi-arch manifest for ${OWNER}/${REPO}"
+
+          # GitHub Container Registry manifests
+          # Create one manifest with both latest and version tags
+          docker buildx imagetools create \
+            --annotation "index:org.opencontainers.image.title=${{ needs.prepare.outputs.repo_name }}" \
+            --annotation "index:org.opencontainers.image.description=Your ultimate IPTV & stream Management companion." \
+            --annotation "index:org.opencontainers.image.url=https://github.com/${{ github.repository }}" \
+            --annotation "index:org.opencontainers.image.source=https://github.com/${{ github.repository }}" \
+            --annotation "index:org.opencontainers.image.version=${VERSION}" \
+            --annotation "index:org.opencontainers.image.created=${TIMESTAMP}" \
+            --annotation "index:org.opencontainers.image.revision=${{ github.sha }}" \
+            --annotation "index:org.opencontainers.image.licenses=See repository" \
+            --annotation "index:org.opencontainers.image.documentation=https://dispatcharr.github.io/Dispatcharr-Docs/" \
+            --annotation "index:org.opencontainers.image.vendor=${OWNER}" \
+            --annotation "index:org.opencontainers.image.authors=${{ github.actor }}" \
+            --annotation "index:maintainer=${{ github.actor }}" \
+            --annotation "index:build_version=Dispatcharr version: ${VERSION} Build date: ${TIMESTAMP}" \
+            --tag ghcr.io/${OWNER}/${REPO}:latest \
+            --tag ghcr.io/${OWNER}/${REPO}:${VERSION} \
+            ghcr.io/${OWNER}/${REPO}:${VERSION}-amd64 ghcr.io/${OWNER}/${REPO}:${VERSION}-arm64
+
+          # Docker Hub manifests
+          # Create one manifest with both latest and version tags
+          docker buildx imagetools create \
+            --annotation "index:org.opencontainers.image.title=${{ needs.prepare.outputs.repo_name }}" \
+            --annotation "index:org.opencontainers.image.description=Your ultimate IPTV & stream Management companion." \
+            --annotation "index:org.opencontainers.image.url=https://github.com/${{ github.repository }}" \
+            --annotation "index:org.opencontainers.image.source=https://github.com/${{ github.repository }}" \
+            --annotation "index:org.opencontainers.image.version=${VERSION}" \
+            --annotation "index:org.opencontainers.image.created=${TIMESTAMP}" \
+            --annotation "index:org.opencontainers.image.revision=${{ github.sha }}" \
+            --annotation "index:org.opencontainers.image.licenses=See repository" \
+            --annotation "index:org.opencontainers.image.documentation=https://dispatcharr.github.io/Dispatcharr-Docs/" \
+            --annotation "index:org.opencontainers.image.vendor=${OWNER}" \
+            --annotation "index:org.opencontainers.image.authors=${{ github.actor }}" \
+            --annotation "index:maintainer=${{ github.actor }}" \
+            --annotation "index:build_version=Dispatcharr version: ${VERSION} Build date: ${TIMESTAMP}" \
+            --tag docker.io/${{ secrets.DOCKERHUB_ORGANIZATION }}/${REPO}:latest \
+            --tag docker.io/${{ secrets.DOCKERHUB_ORGANIZATION }}/${REPO}:${VERSION} \
+            docker.io/${{ secrets.DOCKERHUB_ORGANIZATION }}/${REPO}:${VERSION}-amd64 docker.io/${{ secrets.DOCKERHUB_ORGANIZATION }}/${REPO}:${VERSION}-arm64
+
+  create-release:
+    needs: [prepare, create-manifest]
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: v${{ needs.prepare.outputs.new_version }}
+          name: Release v${{ needs.prepare.outputs.new_version }}
+          draft: false
+          prerelease: false
+          token: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -0,0 +1,24 @@
+.DS_Store
+**/__pycache__/
+**/.vscode/
+**/venv
+*.pyc
+node_modules/
+.history/
+staticfiles/
+docker/DockerfileAIO
+docker/Dockerfile DEV
+static/
+data/
+.next
+next-env.d.ts
+media/
+celerybeat-schedule*
+dump.rdb
+debugpy*
+uwsgi.sock
+package-lock.json
+models
+.idea
+.vite/
+uv.lock

.python-version

@@ -0,0 +1 @@
+3.13

CONTRIBUTING.md

@@ -0,0 +1,245 @@
+# Contributing to Dispatcharr
+
+Thank you for your interest in contributing. Dispatcharr is a complex, production-oriented platform and we hold contributions to a high standard. Please read this guide in full before opening a pull request — it will save everyone time.
+
+---
+
+## Table of Contents
+
+- [Before You Start](#before-you-start)
+- [Project Overview](#project-overview)
+- [Setting Up the Development Environment](#setting-up-the-development-environment)
+- [Code Standards](#code-standards)
+- [Writing Tests](#writing-tests)
+- [Submitting a Pull Request](#submitting-a-pull-request)
+- [On AI-Assisted Code](#on-ai-assisted-code)
+- [What We Will Decline](#what-we-will-decline)
+- [Contributor License Agreement](#contributor-license-agreement)
+
+---
+
+## Before You Start
+
+**Open an issue before writing code.** If you want to add a feature or fix a non-trivial bug, open a GitHub issue first. This lets us tell you whether it aligns with the project's direction, whether it's already being worked on, and how it should be approached — before you invest time writing code.
+
+For small, obvious bug fixes (a typo, an off-by-one error, a missing validation) you can go straight to a PR.
+
+---
+
+## Project Overview
+
+Understanding the architecture is a prerequisite for contributing. If you are not familiar with the following, take time to learn them before submitting changes:
+
+| Layer       | Technology                                        |
+| ----------- | ------------------------------------------------- |
+| Backend     | Python 3.13, Django 5, Django REST Framework      |
+| Async tasks | Celery 5 with Redis broker                        |
+| Real-time   | Django Channels (WebSockets), Redis channel layer |
+| Database    | PostgreSQL 17                                     |
+| Frontend    | React 19, Vite, Mantine UI, Zustand               |
+| API docs    | drf-spectacular (OpenAPI)                         |
+| Packaging   | `uv`, `pyproject.toml`, Hatchling                 |
+| Deployment  | Docker, Nginx, uWSGI/Daphne                       |
+
+### Key Django Apps
+
+| App             | Responsibility                                        |
+| --------------- | ----------------------------------------------------- |
+| `apps/channels` | Core channel management                               |
+| `apps/proxy`    | Stream proxying, client management, failover          |
+| `apps/epg`      | EPG ingestion, matching, XMLTV output                 |
+| `apps/m3u`      | M3U playlist parsing and management                   |
+| `apps/output`   | M3U, Xtream Codes, XMLTV export                       |
+| `apps/hdhr`     | HDHomeRun device emulation                            |
+| `apps/vod`      | VOD library with TMDB/IMDB metadata                   |
+| `apps/ffmpeg`   | FFmpeg stream profile management                      |
+| `apps/plugins`  | Plugin/event-hook system                              |
+| `apps/accounts` | Auth, permissions, API keys                           |
+| `core/`         | Shared tasks, scheduling, utilities, Xtream Codes API |
+
+Before touching any app, read its models, serializers, and views end-to-end so you understand what already exists.
+
+---
+
+## Setting Up the Development Environment
+
+### Prerequisites
+
+- Docker and Docker Compose
+- Node.js 24+ (for frontend)
+- Python 3.13+ and [`uv`](https://docs.astral.sh/uv/)
+
+### Backend (Docker — recommended)
+
+```bash
+# Full stack (modular mode with separate containers)
+docker compose -f docker/docker-compose.dev.yml up
+
+# Or run Django directly against a local Redis/Postgres
+uv sync
+uv run python manage.py migrate
+uv run python manage.py runserver
+```
+
+### Frontend
+
+```bash
+cd frontend
+npm install
+npm run dev       # dev server with HMR (proxies API to Django)
+npm run build     # production build
+npm run test      # run Vitest test suite
+```
+
+The Vite dev server is configured to proxy `/api/` requests to the Django backend.
+
+### Environment Variables
+
+Copy the relevant `docker-compose.*.yml` as a reference for required environment variables. Key ones:
+
+| Variable                | Purpose                                                                                     |
+| ----------------------- | ------------------------------------------------------------------------------------------- |
+| `POSTGRES_*`            | Database connection                                                                         |
+| `REDIS_*`               | Redis broker / channel layer                                                                |
+| `DJANGO_SECRET_KEY`     | Django secret (auto-generated in Docker)                                                    |
+| `DISPATCHARR_DEBUG`     | Enables Django debug mode **and** starts debugpy for remote debugging (attach on port 5678) |
+| `DISPATCHARR_LOG_LEVEL` | Log verbosity                                                                               |
+
+---
+
+## Code Standards
+
+### Backend (Python/Django)
+
+- Follow [PEP 8](https://peps.python.org/pep-0008/). Use 4-space indentation.
+- Follow Django conventions: fat models, thin views, business logic out of serializers.
+- New API endpoints must use Django REST Framework. Include serializers — do not return raw dicts from views.
+- New endpoints must be registered in the appropriate `api_urls.py` and must appear correctly in the OpenAPI schema (check via drf-spectacular).
+- Database changes require a migration: `uv run python manage.py makemigrations <app>`. Migrations must be included in your PR.
+- Celery tasks belong in `tasks.py` of the relevant app, or `core/tasks.py` for shared tasks. Tasks must be idempotent where possible.
+- Do not introduce new top-level dependencies without discussion. Add them to `pyproject.toml` with a justification in your PR description.
+
+### Frontend (React/JavaScript)
+
+- Code must pass ESLint without errors: `npm run lint`
+- Code must be formatted with Prettier: `npm run format`
+- Use existing Mantine UI components. Do not introduce new UI libraries.
+- State management uses Zustand. New global state belongs in a store under `frontend/src/store/`. Do not use React Context for app-level state.
+- API calls belong in `frontend/src/api.js`. Do not make `fetch`/`axios` calls directly from components.
+- Components should be functional. Avoid class components.
+
+### General
+
+- Do not leave debug logging, `console.log`, `print()`, or commented-out code in your PR.
+- Do not reformat or refactor code outside the scope of your change. Noise in diffs makes review harder.
+- Keep commits focused. One logical change per commit.
+
+---
+
+## Writing Tests
+
+Untested code is significantly less likely to be merged.
+
+### Backend
+
+- Use Django's `TestCase` for unit/integration tests.
+- Test files live at `apps/<app>/tests/`.
+- Run the test suite with: `uv run python manage.py test`
+
+### Frontend
+
+- Use Vitest and React Testing Library.
+- Test files live alongside what they test in `__tests__/` directories.
+- Run with: `npm run test`
+- Every new store should have a test file under `frontend/src/store/__tests__/`.
+- Every new page should have a test file under `frontend/src/pages/__tests__/`.
+
+---
+
+## Submitting a Pull Request
+
+### PR Checklist
+
+Before opening your PR, verify each of the following yourself:
+
+- [ ] I have read this entire document
+- [ ] I opened (or was assigned to) a GitHub issue for this change before writing code
+- [ ] I understand — line by line — every change in this PR
+- [ ] Backend: migrations are included if models changed
+- [ ] Backend: new endpoints are documented in the OpenAPI schema
+- [ ] Frontend: ESLint and Prettier pass cleanly
+- [ ] Tests are included for new functionality
+- [ ] Existing tests still pass
+- [ ] No debug artifacts are left in the code
+- [ ] My PR targets the `dev` branch (or the branch specified in the issue)
+
+### PR Description
+
+A good PR description answers:
+
+1. **What** does this change do?
+2. **Why** is this change needed? (link to the issue)
+3. **How** does it work? Describe any non-obvious technical decisions.
+4. **How was it tested?** What did you run to verify this works?
+
+One-line PR descriptions like _"fixed bug"_ or _"added feature"_ will be closed and asked to resubmit.
+
+### Review Process
+
+Maintainers review PRs as time allows. To keep the process moving:
+
+- Respond to review comments promptly. Stale PRs (no activity for 30 days) may be closed.
+- Do not force-push to a branch under review without flagging it in a comment.
+- Keep your branch up to date with `dev` by rebasing, not merging `dev` into your branch.
+
+---
+
+## On AI-Assisted Code
+
+We are aware that AI coding tools are capable of generating plausible-looking code quickly. We do not prohibit their use, but we require the following:
+
+**You must understand every line of code you submit.**
+
+AI tools frequently produce code that:
+
+- Duplicates logic that already exists elsewhere in the codebase
+- Ignores the established patterns for how the project is structured
+- Introduces subtle bugs that are invisible without domain knowledge
+- Passes superficial review but breaks edge cases in production
+
+If you cannot explain, during code review, why a particular line of code is written the way it is — including the tradeoffs involved — the PR will not be merged. There are no exceptions.
+
+Using an AI tool to help you understand the codebase, generate a first draft, or write boilerplate is fine. Submitting code you have not read and do not understand is not.
+
+---
+
+## What We Will Decline
+
+To save your time and ours, the following types of PRs will be closed without extended review:
+
+- **Undiscussed feature additions.** If there is no linked issue where the feature was agreed upon, we will close the PR and ask you to open one.
+- **Large, unfocused diffs.** A PR that touches 20 files across 5 apps to "improve code quality" is almost never reviewable. Scope your changes.
+- **Dependency bumps without justification.** Don't open a PR just to bump a library version unless you have identified a specific bug or security issue it resolves.
+- **Cosmetic/style-only changes.** Reformatting files, renaming variables for preference, or reorganizing imports with no functional change.
+- **Duplicate work.** Check open PRs and issues before starting. If someone is already working on it, coordinate with them.
+- **Code the author cannot explain.** See [On AI-Assisted Code](#on-ai-assisted-code).
+
+---
+
+## Contributor License Agreement
+
+By submitting a pull request to this repository, you agree to the following terms:
+
+- You authored the contribution and have the right to submit it.
+- You grant the Dispatcharr project a perpetual, worldwide, irrevocable, royalty-free license to use, reproduce, modify, distribute, sublicense, and relicense your contribution as part of this project, under any license the project maintainers choose, now or in the future.
+- You retain your own copyright in your contribution — this is a license grant, not a transfer of ownership.
+
+This ensures you always retain the right to use your own contribution elsewhere, while the project isn't blocked from making licensing decisions by the need to track down every past contributor.
+
+By checking the CLA checkbox in the pull request checklist, you confirm that you have read and agree to these terms.
+
+---
+
+## Questions
+
+If you are unsure whether a contribution is a good fit, join the [Discord](https://discord.gg/Sp45V5BcxU) and start a conversation, or comment on the relevant issue. We would rather have a five-minute conversation upfront than a 30-comment review thread on a PR that ultimately doesn't get merged.

LICENSE

@@ -0,0 +1,661 @@
+                    GNU AFFERO GENERAL PUBLIC LICENSE
+                       Version 3, 19 November 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU Affero General Public License is a free, copyleft license for
+software and other kinds of works, specifically designed to ensure
+cooperation with the community in the case of network server software.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+our General Public Licenses are intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+  Developers that use our General Public Licenses protect your rights
+with two steps: (1) assert copyright on the software, and (2) offer
+you this License which gives you legal permission to copy, distribute
+and/or modify the software.
+
+  A secondary benefit of defending all users' freedom is that
+improvements made in alternate versions of the program, if they
+receive widespread use, become available for other developers to
+incorporate.  Many developers of free software are heartened and
+encouraged by the resulting cooperation.  However, in the case of
+software used on network servers, this result may fail to come about.
+The GNU General Public License permits making a modified version and
+letting the public access it on a server without ever releasing its
+source code to the public.
+
+  The GNU Affero General Public License is designed specifically to
+ensure that, in such cases, the modified source code becomes available
+to the community.  It requires the operator of a network server to
+provide the source code of the modified version running there to the
+users of that server.  Therefore, public use of a modified version, on
+a publicly accessible server, gives the public access to the source
+code of the modified version.
+
+  An older license, called the Affero General Public License and
+published by Affero, was designed to accomplish similar goals.  This is
+a different license, not a version of the Affero GPL, but Affero has
+released a new version of the Affero GPL which permits relicensing under
+this license.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                       TERMS AND CONDITIONS
+
+  0. Definitions.
+
+  "This License" refers to version 3 of the GNU Affero General Public License.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+  "The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+  To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+  A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+  To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+  To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+  An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+  1. Source Code.
+
+  The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
+
+  A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+  The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+  The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+  The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+  The Corresponding Source for a work in source code form is that
+same work.
+
+  2. Basic Permissions.
+
+  All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+  You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force.  You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright.  Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+  Conveying under any other circumstances is permitted solely under
+the conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+  No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+  When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+  4. Conveying Verbatim Copies.
+
+  You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+  You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+  5. Conveying Modified Source Versions.
+
+  You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+    a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+
+    b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under section
+    7.  This requirement modifies the requirement in section 4 to
+    "keep intact all notices".
+
+    c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy.  This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged.  This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+
+    d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+  A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit.  Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+  6. Conveying Non-Source Forms.
+
+  You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+    a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+
+    b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for as
+    long as you offer spare parts or customer support for that product
+    model, to give anyone who possesses the object code either (1) a
+    copy of the Corresponding Source for all the software in the
+    product that is covered by this License, on a durable physical
+    medium customarily used for software interchange, for a price no
+    more than your reasonable cost of physically performing this
+    conveying of source, or (2) access to copy the
+    Corresponding Source from a network server at no charge.
+
+    c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source.  This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in accord
+    with subsection 6b.
+
+    d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to the
+    Corresponding Source in the same way through the same place at no
+    further charge.  You need not require recipients to copy the
+    Corresponding Source along with the object code.  If the place to
+    copy the object code is a network server, the Corresponding Source
+    may be on a different server (operated by you or a third party)
+    that supports equivalent copying facilities, provided you maintain
+    clear directions next to the object code saying where to find the
+    Corresponding Source.  Regardless of what server hosts the
+    Corresponding Source, you remain obligated to ensure that it is
+    available for as long as needed to satisfy these requirements.
+
+    e) Convey the object code using peer-to-peer transmission, provided
+    you inform other peers where the object code and Corresponding
+    Source of the work are being offered to the general public at no
+    charge under subsection 6d.
+
+  A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+  A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling.  In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage.  For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product.  A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+  "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source.  The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+  If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information.  But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+  The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed.  Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+  Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+  7. Additional Terms.
+
+  "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law.  If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+  When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it.  (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.)  You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+  Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+    a) Disclaiming warranty or limiting liability differently from the
+    terms of sections 15 and 16 of this License; or
+
+    b) Requiring preservation of specified reasonable legal notices or
+    author attributions in that material or in the Appropriate Legal
+    Notices displayed by works containing it; or
+
+    c) Prohibiting misrepresentation of the origin of that material, or
+    requiring that modified versions of such material be marked in
+    reasonable ways as different from the original version; or
+
+    d) Limiting the use for publicity purposes of names of licensors or
+    authors of the material; or
+
+    e) Declining to grant rights under trademark law for use of some
+    trade names, trademarks, or service marks; or
+
+    f) Requiring indemnification of licensors and authors of that
+    material by anyone who conveys the material (or modified versions of
+    it) with contractual assumptions of liability to the recipient, for
+    any liability that these contractual assumptions directly impose on
+    those licensors and authors.
+
+  All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10.  If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term.  If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+  If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+  Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+  8. Termination.
+
+  You may not propagate or modify a covered work except as expressly
+provided under this License.  Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+  However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+  Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+  Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+  9. Acceptance Not Required for Having Copies.
+
+  You are not required to accept this License in order to receive or
+run a copy of the Program.  Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance.  However,
+nothing other than this License grants you permission to propagate or
+modify any covered work.  These actions infringe copyright if you do
+not accept this License.  Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+  10. Automatic Licensing of Downstream Recipients.
+
+  Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.  You are not responsible
+for enforcing compliance by third parties with this License.
+
+  An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations.  If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+  You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License.  For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+  11. Patents.
+
+  A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.  The
+work thus licensed is called the contributor's "contributor version".
+
+  A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version.  For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+  Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+  In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement).  To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+  If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients.  "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+  If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+  A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License.  You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+  Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+  12. No Surrender of Others' Freedom.
+
+  If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all.  For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+  13. Remote Network Interaction; Use with the GNU General Public License.
+
+  Notwithstanding any other provision of this License, if you modify the
+Program, your modified version must prominently offer all users
+interacting with it remotely through a computer network (if your version
+supports such interaction) an opportunity to receive the Corresponding
+Source of your version by providing access to the Corresponding Source
+from a network server at no charge, through some standard or customary
+means of facilitating copying of software.  This Corresponding Source
+shall include the Corresponding Source for any work covered by version 3
+of the GNU General Public License that is incorporated pursuant to the
+following paragraph.
+
+  Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU General Public License into a single
+combined work, and to convey the resulting work.  The terms of this
+License will continue to apply to the part which is the covered work,
+but the work with which it is combined will remain governed by version
+3 of the GNU General Public License.
+
+  14. Revised Versions of this License.
+
+  The Free Software Foundation may publish revised and/or new versions of
+the GNU Affero General Public License from time to time.  Such new versions
+will be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+  Each version is given a distinguishing version number.  If the
+Program specifies that a certain numbered version of the GNU Affero General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation.  If the Program does not specify a version number of the
+GNU Affero General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+  If the Program specifies that a proxy can decide which future
+versions of the GNU Affero General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+  Later license versions may give you additional or different
+permissions.  However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+  15. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+  17. Interpretation of Sections 15 and 16.
+
+  If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Affero General Public License as published
+    by the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU Affero General Public License for more details.
+
+    You should have received a copy of the GNU Affero General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+  If your software can interact with users remotely through a computer
+network, you should also make sure that it provides a way for users to
+get its source.  For example, if your program is a web application, its
+interface could display a "Source" link that leads users to an archive
+of the code.  There are many ways you could offer source, and different
+solutions will be better for different programs; see section 13 for the
+specific requirements.
+
+  You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU AGPL, see
+<https://www.gnu.org/licenses/>.

Plugin_repo.md

@@ -0,0 +1,586 @@
+# Dispatcharr Plugin Repository Specification
+
+How to create and host a plugin repository that Dispatcharr can consume.
+
+For writing plugins themselves, see [Plugins.md](Plugins.md).
+
+---
+
+## Overview
+
+Dispatcharr discovers plugins from remote repositories using a two-level manifest system:
+
+1. **Repo manifest** - a JSON file listing all plugins in the repo with basic metadata.
+2. **Per-plugin manifest** (optional) - a JSON file per plugin with full version history, checksums, and compatibility info.
+
+Users add a repo by its manifest URL. Dispatcharr fetches and caches the repo manifest periodically (default: every 6 hours, configurable). The UI displays all plugins from enabled repos in a browsable store.
+
+---
+
+## Repo Manifest
+
+The repo manifest is the entry point. Dispatcharr fetches this URL and caches the response.
+
+### Minimal Example (no signing)
+
+```json
+{
+  "registry_name": "My Plugin Repo",
+  "plugins": [
+    {
+      "slug": "my_plugin",
+      "name": "My Plugin",
+      "description": "Does something useful",
+      "author": "Your Name",
+      "latest_version": "1.0.0",
+      "latest_url": "https://example.com/releases/my_plugin-1.0.0.zip"
+    }
+  ]
+}
+```
+
+This is the simplest valid repo manifest - one plugin with enough info to show in the store and install.
+
+### Full Example (with signing)
+
+```json
+{
+  "manifest": {
+    "registry_name": "My Plugin Repo",
+    "registry_url": "https://github.com/myorg/my-plugins",
+    "root_url": "https://raw.githubusercontent.com/myorg/my-plugins/releases",
+    "plugins": [
+      {
+        "slug": "weather_display",
+        "name": "Weather Display",
+        "description": "Shows weather info on the dashboard",
+        "author": "Acme Labs",
+        "license": "MIT",
+        "latest_version": "1.2.5",
+        "last_updated": "2025-01-20T15:30:00Z",
+        "manifest_url": "plugins/weather_display/manifest.json",
+        "latest_url": "plugins/weather_display/releases/weather_display-1.2.5.zip",
+        "latest_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+        "icon_url": "plugins/weather_display/logo.png",
+        "min_dispatcharr_version": "2.5.0",
+        "max_dispatcharr_version": null
+      }
+    ]
+  },
+  "signature": "-----BEGIN PGP SIGNATURE-----\n..."
+}
+```
+
+### Accepted Formats
+
+Dispatcharr accepts two top-level shapes:
+
+**Wrapped (supports signing):**
+```json
+{
+  "manifest": { "plugins": [...], ... },
+  "signature": "..."
+}
+```
+
+**Flat (no signing):**
+```json
+{
+  "plugins": [...],
+  "registry_name": "...",
+  "root_url": "..."
+}
+```
+
+The wrapped format is required for signing. If you don't need signing, the flat format works and is simpler.
+
+### Name Restrictions
+
+`registry_name` is required. Dispatcharr rejects repos that are missing it.
+
+Third-party repos must not use names that could be confused with an official Dispatcharr repo. The following words are blocked in `registry_name` (case-insensitive):
+
+- "official"
+- "dispatcharr plugins"
+- "dispatcharr repo"
+- "dispatcharr official"
+
+If the name contains any of these, the repo will be rejected on add and skipped during refresh.
+
+---
+
+## Repo Manifest Fields
+
+### Top-Level Metadata
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `registry_name` | **Yes** | Display name for the repo. Must not contain words like "official" or "dispatcharr" that could be mistaken for an official repo (see [Name Restrictions](#name-restrictions)). |
+| `registry_url` | No | URL to the repo's home page (e.g. GitHub). Used as a fallback for generating icon URLs. |
+| `root_url` | No | Base URL for resolving relative URLs in plugin entries. Trailing slashes are stripped. |
+| `plugins` | **Yes** | Array of plugin entry objects. |
+
+### Plugin Entry Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `slug` | **Yes** | Unique identifier. Alphanumeric, dashes, and underscores. Used as the install directory name (lowercased, dashes converted to underscores). |
+| `name` | **Yes** | Human-readable display name. |
+| `description` | No | Short description shown on the plugin card. |
+| `author` | No | Author or organization name. |
+| `license` | No | SPDX license identifier (e.g. `MIT`, `GPL-3.0`). Displayed as a link to the SPDX license page. |
+| `latest_version` | No | Current latest version string (semver: `1.2.3` or `v1.2.3`). Drives update detection. |
+| `last_updated` | No | ISO 8601 timestamp of the latest release. Shown as "Built" date in the detail view. |
+| `manifest_url` | No | URL (or relative path) to the per-plugin manifest with full version history. See [Per-Plugin Manifest](#per-plugin-manifest). |
+| `latest_url` | No | Direct download URL (or relative path) to the latest release zip. |
+| `latest_sha256` | No | SHA256 checksum of the latest release zip (lowercase hex, 64 chars). |
+| `latest_md5` | No | MD5 checksum of the latest release zip. Informational only - not validated by Dispatcharr. |
+| `icon_url` | No | URL (or relative path) to a logo image (PNG recommended). |
+| `min_dispatcharr_version` | No | Minimum Dispatcharr version required. Install is blocked if the running version is older. |
+| `max_dispatcharr_version` | No | Maximum Dispatcharr version supported. Install is blocked if the running version is newer. |
+
+Extra fields in a plugin entry are passed through to the frontend as-is, so you can include custom metadata (e.g. `homepage`, `tags`) without breaking anything.
+
+### URL Resolution
+
+If `root_url` is set and a URL field (`manifest_url`, `latest_url`, `icon_url`) does not start with `http://` or `https://`, it is treated as relative and resolved as:
+
+```
+{root_url}/{field_value}
+```
+
+This lets you keep plugin entries compact:
+```json
+{
+  "root_url": "https://raw.githubusercontent.com/myorg/my-plugins/releases",
+  "plugins": [
+    {
+      "slug": "my_plugin",
+      "latest_url": "plugins/my_plugin/my_plugin-1.0.0.zip",
+      "icon_url": "plugins/my_plugin/logo.png",
+      "manifest_url": "plugins/my_plugin/manifest.json"
+    }
+  ]
+}
+```
+
+**Icon fallback:** If `icon_url` is missing and `registry_url` is set, Dispatcharr generates a fallback URL by converting the GitHub URL to a raw content URL:
+```
+{registry_url => raw.githubusercontent.com}/refs/heads/main/plugins/{slug}/logo.png
+```
+
+---
+
+## Per-Plugin Manifest (Optional)
+
+The per-plugin manifest provides full version history. It is fetched on-demand when a user clicks "More Info" on a plugin card. It is **not required** - if `manifest_url` is absent, the UI builds a detail view from the repo-level fields instead.
+
+Include a per-plugin manifest if you want to:
+- Offer multiple downloadable versions
+- Show per-version compatibility ranges
+- Display build timestamps and commit links for each version
+- Provide detailed author/license info beyond what's in the repo manifest
+
+### Accepted Formats
+
+Same as the root manifest - both flat and wrapped formats are accepted:
+
+**Flat (no signing):**
+```json
+{
+  "slug": "...",
+  "versions": [...]
+}
+```
+
+**Wrapped (supports signing):**
+```json
+{
+  "manifest": {
+    "slug": "...",
+    "versions": [...]
+  },
+  "signature": "-----BEGIN PGP SIGNATURE-----\n..."
+}
+```
+
+Use the wrapped format if you want to GPG-sign the per-plugin manifest.
+
+### Example
+
+```json
+{
+  "slug": "weather_display",
+  "name": "Weather Display",
+  "description": "Shows weather information on the Dispatcharr dashboard",
+  "author": "Acme Labs",
+  "license": "MIT",
+  "latest_version": "1.2.5",
+  "versions": [
+    {
+      "version": "1.2.5",
+      "url": "releases/weather_display-1.2.5.zip",
+      "checksum_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+      "build_timestamp": "2025-01-20T15:30:00Z",
+      "commit_sha": "4e8f1b108c1e84f60520710d13e54eb2fb519648",
+      "commit_sha_short": "4e8f1b1",
+      "min_dispatcharr_version": "2.5.0",
+      "max_dispatcharr_version": null
+    },
+    {
+      "version": "1.2.5-rc.1",
+      "url": "releases/weather_display-1.2.5-rc.1.zip",
+      "checksum_sha256": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
+      "prerelease": true,
+      "build_timestamp": "2025-01-18T09:00:00Z",
+      "min_dispatcharr_version": "2.5.0"
+    },
+    {
+      "version": "1.2.4",
+      "url": "releases/weather_display-1.2.4.zip",
+      "checksum_sha256": "d4d967a67a4947e55183308cece206b30dda3e1b4fe00aae60f45a49c83b7ed6",
+      "build_timestamp": "2025-01-15T10:00:00Z",
+      "min_dispatcharr_version": "2.4.0"
+    }
+  ],
+  "latest": {
+    "version": "1.2.5",
+    "url": "releases/weather_display-1.2.5.zip",
+    "checksum_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+    "build_timestamp": "2025-01-20T15:30:00Z",
+    "min_dispatcharr_version": "2.5.0"
+  }
+}
+```
+
+### Per-Plugin Manifest Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `slug` | No | Plugin identifier (should match the repo entry). |
+| `name` | No | Display name. |
+| `description` | No | Full description shown in the detail modal. |
+| `author` | No | Author/org name shown in the detail modal. |
+| `license` | No | SPDX license identifier. |
+| `latest_version` | No | Latest version string. |
+| `versions` | No | Array of version objects (newest first recommended). |
+| `latest` | No | Object mirroring the latest version entry for quick access. |
+
+### Version Object Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `version` | **Yes** | Version string (`1.2.3` or `v1.2.3`). |
+| `url` | **Yes** | Download URL for the zip. Relative URLs are resolved against the repo's `root_url`. |
+| `checksum_sha256` | No | SHA256 hex checksum. **Strongly recommended.** Validated on install - mismatch blocks the install. |
+| `prerelease` | No | Boolean. When `true`, marks this version as a pre-release (alpha, beta, RC, etc.). If the installed version is a prerelease, Dispatcharr will not suggest updating to the latest stable version - the user must install a new version manually. The latest version in the root manifest is always assumed to be stable, so this field only needs to appear in the per-plugin manifest. Omit or set to `false` for stable releases. |
+| `build_timestamp` | No | ISO 8601 build timestamp. Shown as "Built" in the version detail. |
+| `commit_sha` | No | Full Git commit SHA. Used to build a commit link if `registry_url` is set. |
+| `commit_sha_short` | No | Abbreviated commit SHA. Displayed in the version detail table as a clickable link. |
+| `min_dispatcharr_version` | No | Minimum compatible Dispatcharr version. |
+| `max_dispatcharr_version` | No | Maximum compatible Dispatcharr version. |
+
+Relative `url` values in versions are resolved the same way as repo-level URLs: `{root_url}/{url}`.
+
+---
+
+## Without a Per-Plugin Manifest
+
+If you omit `manifest_url` from a plugin entry, the store still works. When a user clicks "More Info", the UI builds a detail view from the repo-level fields:
+
+- `description`, `author`, `license` from the plugin entry
+- A single version entry built from `latest_version`, `latest_url`, `latest_sha256`, `min_dispatcharr_version`, `max_dispatcharr_version`, and `last_updated`
+
+This is the simplest path for third-party repos that only publish one version at a time. You lose version history and per-version release dates, but install, update detection, and everything else works the same.
+
+---
+
+## Signing
+
+Signing your repo manifest lets Dispatcharr verify it hasn't been tampered with. Signing is **optional** - unsigned repos work fine but show an "unverified" badge in the UI.
+
+### How It Works
+
+1. You generate a GPG keypair.
+2. You sign the manifest JSON and include the detached signature in the response.
+3. When adding the repo in Dispatcharr, the user pastes your public key.
+4. Dispatcharr verifies the signature on every manifest fetch.
+
+### Key Format
+
+Standard PGP/GPG armored keys:
+
+```
+-----BEGIN PGP PUBLIC KEY BLOCK-----
+
+mQINBG...
+...
+-----END PGP PUBLIC KEY BLOCK-----
+```
+
+### Signing Convention
+
+The signature is computed over the **canonical JSON** representation of the `manifest` object (not the entire response), plus a trailing newline:
+
+```bash
+# Canonical format: compact JSON (no spaces) + trailing newline
+jq -c '.manifest' manifest.json | gpg --armor --detach-sign
+```
+
+In code terms:
+```python
+import json
+canonical = json.dumps(manifest_obj, separators=(",", ":")) + "\n"
+```
+
+> **Important:** The signing input must be `json.dumps(obj, separators=(",", ":")) + "\n"` - compact JSON with no whitespace, followed by exactly one newline. Any difference (pretty-printing, trailing spaces, key ordering changes) will cause verification to fail.
+
+### Manifest Structure for Signing
+
+Use the wrapped format so the signature sits alongside the manifest:
+
+```json
+{
+  "manifest": {
+    "registry_name": "...",
+    "plugins": [...]
+  },
+  "signature": "-----BEGIN PGP SIGNATURE-----\n...\n-----END PGP SIGNATURE-----"
+}
+```
+
+### Verification Results
+
+| Result | Meaning | UI Badge |
+|--------|---------|----------|
+| `true` | Valid signature | Green checkmark |
+| `false` | Invalid signature or verification error | Red X |
+| `null` | Not attempted (no signature, no key, or `python-gnupg` not installed) | Gray/neutral |
+
+### Signing Workflow Example
+
+```bash
+# Generate a keypair (one-time)
+gpg --gen-key
+
+# Export your public key (give this to repo users)
+gpg --armor --export "your@email.com" > my-repo.pub
+
+# Build your manifest
+cat > manifest.json << 'EOF'
+{
+  "manifest": {
+    "registry_name": "My Repo",
+    "root_url": "https://example.com/releases",
+    "plugins": [
+      {
+        "slug": "my_plugin",
+        "name": "My Plugin",
+        "latest_version": "1.0.0",
+        "latest_url": "plugins/my_plugin/my_plugin-1.0.0.zip"
+      }
+    ]
+  }
+}
+EOF
+
+# Sign the manifest object (canonical JSON + newline)
+jq -c '.manifest' manifest.json | gpg --armor --detach-sign > manifest.sig
+
+# Combine into final output
+jq --arg sig "$(cat manifest.sig)" '.signature = $sig' manifest.json > signed_manifest.json
+```
+
+### Third-Party Key Management
+
+When a user adds your repo URL, they can paste your public key. Dispatcharr stores the key per-repo and uses it for verification. Users can update the key at any time from the repo management UI.
+
+If you don't provide a key and the repo is not the official Dispatcharr repo, signature verification is skipped (result: `null`).
+
+---
+
+## Release Zip Format
+
+Each plugin release is a `.zip` archive.
+
+### Requirements
+
+- Must contain a `plugin.py` with a `Plugin` class, **or** a Python package with `__init__.py` exporting a `Plugin` class.
+- Files can be at the top level of the zip or inside a single subdirectory.
+- Optionally include `plugin.json` for metadata discovery without code execution.
+- Optionally include `logo.png` for the plugin icon.
+
+### Size Limits
+
+- Maximum 2000 files per archive.
+- Maximum total size: 200 MB (configurable via `MAX_PLUGIN_IMPORT_BYTES` setting).
+
+### Recommended Structure
+
+```
+my_plugin-1.0.0.zip
+  plugin.py
+  plugin.json
+  logo.png
+  (any other files your plugin needs)
+```
+
+Or with a subdirectory:
+```
+my_plugin-1.0.0.zip
+  my_plugin/
+    plugin.py
+    plugin.json
+    logo.png
+    utils.py
+```
+
+---
+
+## Install Flow
+
+When a user installs a plugin from the store:
+
+1. **Version compatibility check** - if `min_dispatcharr_version` or `max_dispatcharr_version` is set, the running Dispatcharr version is compared. Install is blocked if out of range.
+2. **Download** - the zip is streamed from `download_url` (max 200 MB).
+3. **SHA256 integrity check** - if `sha256` was provided, the download is hashed and compared. Mismatch blocks the install.
+4. **Extraction** - the zip is extracted to a temp directory, validated, then moved to `/data/plugins/{plugin_key}/`. If the plugin already exists, the old version is backed up and restored on failure (atomic rollback).
+5. **Registration** - a `PluginConfig` record is created or updated, linking the plugin to its source repo and slug.
+6. **Discovery reload** - the plugin loader re-scans all plugin directories.
+
+The plugin is installed **disabled** by default. The user can enable it from the post-install dialog or the My Plugins page.
+
+---
+
+## Update Detection
+
+Dispatcharr detects updates by comparing `installed_version` (stored in the database) against `latest_version` from the repo manifest. This uses repo-level fields only - per-plugin manifests are not needed for update detection.
+
+A plugin shows "Update Available" when:
+- It is managed (installed from a repo)
+- Its `installed_version` differs from `latest_version`
+- It was installed from the same repo
+
+---
+
+## Hosting Options
+
+A plugin repo manifest is just a JSON file served over HTTPS. Some options:
+
+### GitHub Pages / Raw Content
+Host your manifest and release zips in a GitHub repo. Use raw.githubusercontent.com URLs:
+```
+https://raw.githubusercontent.com/myorg/my-plugins/main/manifest.json
+```
+
+Use `root_url` pointing to your releases branch/path so version URLs stay relative.
+
+### Static File Server
+Any web server that serves JSON works. Dispatcharr fetches manifests server-side, so CORS is not needed.
+
+### GitHub Releases
+You can host release zips as GitHub Release assets and reference them with absolute URLs in your manifest. The manifest itself can live in the repo's default branch.
+
+---
+
+## Refresh Behavior
+
+- Manifests are refreshed automatically at a configurable interval (default: 6 hours, setting: `refresh_interval_hours`, 0 = disabled).
+- Users can force a refresh from the repo management UI.
+- A new repo is refreshed immediately when added.
+- On refresh, if a plugin's `slug` disappears from the manifest, its `PluginConfig` is unlinked from the repo (becomes "unmanaged") but the installed files are not deleted.
+
+---
+
+## Checklist: Publishing a Plugin Repo
+
+### Minimum Viable Repo
+
+- [ ] Host a JSON file at a stable, public URL
+- [ ] Set `registry_name` (required, must not sound official)
+- [ ] Include at least one plugin entry with `slug`, `name`, and `latest_version`
+- [ ] Host a downloadable `.zip` for each plugin and set `latest_url`
+- [ ] Share the manifest URL with users
+
+### Recommended
+
+- [ ] Set `root_url` so plugin URLs can be relative
+- [ ] Include `description`, `author`, and `icon_url` per plugin
+- [ ] Include `latest_sha256` for integrity verification
+- [ ] Include `license` (SPDX identifier)
+- [ ] Include `last_updated` timestamps
+- [ ] Add a per-plugin `manifest_url` with version history
+- [ ] Include `sha256` in every version object
+- [ ] Include `min_dispatcharr_version` where applicable
+- [ ] Include `plugin.json` in each release zip
+
+### Optional
+
+- [ ] Sign your manifest with GPG and publish your public key
+- [ ] Set `registry_url` to enable automatic icon fallback
+- [ ] Set `max_dispatcharr_version` if a plugin is incompatible with newer releases
+
+---
+
+## Quick Reference: Repo Manifest Schema
+
+```json
+{
+  "manifest": {
+    "registry_name": "string (required)",
+    "registry_url": "string (optional)",
+    "root_url": "string (optional)",
+    "plugins": [
+      {
+        "slug": "string (required)",
+        "name": "string (required)",
+        "description": "string",
+        "author": "string",
+        "license": "string (SPDX)",
+        "latest_version": "string (semver)",
+        "last_updated": "string (ISO 8601)",
+        "manifest_url": "string (URL or relative path)",
+        "latest_url": "string (URL or relative path)",
+        "latest_sha256": "string (64-char hex)",
+        "icon_url": "string (URL or relative path)",
+        "min_dispatcharr_version": "string (semver)",
+        "max_dispatcharr_version": "string (semver) or null"
+      }
+    ]
+  },
+  "signature": "string (armored PGP signature, optional)"
+}
+```
+
+## Quick Reference: Per-Plugin Manifest Schema
+
+```json
+{
+  "slug": "string",
+  "name": "string",
+  "description": "string",
+  "author": "string",
+  "license": "string (SPDX)",
+  "latest_version": "string (semver)",
+  "versions": [
+    {
+      "version": "string (required)",
+      "url": "string (required, URL or relative path)",
+      "checksum_sha256": "string (64-char hex)",
+      "build_timestamp": "string (ISO 8601)",
+      "commit_sha": "string",
+      "commit_sha_short": "string",
+      "min_dispatcharr_version": "string (semver)",
+      "max_dispatcharr_version": "string (semver) or null"
+    }
+  ],
+  "latest": {
+    "version": "string",
+    "url": "string",
+    "checksum_sha256": "string",
+    "build_timestamp": "string",
+    "min_dispatcharr_version": "string",
+    "max_dispatcharr_version": "string or null"
+  }
+}
+```

Plugins.md

@@ -0,0 +1,518 @@
+# Dispatcharr Plugins
+
+This document explains how to build, install, and use Python plugins in Dispatcharr. It covers discovery, the plugin interface, settings, actions, how to access application APIs, and examples.
+
+---
+
+## Quick Start
+
+1) Create a folder under `/app/data/plugins/my_plugin/` (host path `data/plugins/my_plugin/` in the repo).
+
+2) Add a `plugin.json` manifest (new standard) and a `plugin.py` file:
+
+`/app/data/plugins/my_plugin/plugin.json`
+```json
+{
+  "name": "My Plugin",
+  "version": "0.1.0",
+  "description": "Does something useful",
+  "author": "Acme Labs",
+  "help_url": "https://example.com/docs/my-plugin",
+  "fields": [
+    { "id": "enabled", "label": "Enabled", "type": "boolean", "default": true },
+    { "id": "limit", "label": "Item limit", "type": "number", "default": 5 },
+    {
+      "id": "mode",
+      "label": "Mode",
+      "type": "select",
+      "default": "safe",
+      "options": [
+        { "value": "safe", "label": "Safe" },
+        { "value": "fast", "label": "Fast" }
+      ]
+    },
+    { "id": "note", "label": "Note", "type": "string", "default": "" }
+  ],
+  "actions": [
+    {
+      "id": "do_work",
+      "label": "Do Work",
+      "description": "Process items",
+      "button_label": "Run Job",
+      "button_variant": "filled",
+      "button_color": "blue"
+    }
+  ]
+}
+```
+
+```
+# /app/data/plugins/my_plugin/plugin.py
+class Plugin:
+    name = "My Plugin"
+    version = "0.1.0"
+    description = "Does something useful"
+    author = "Acme Labs"
+    help_url = "https://example.com/docs/my-plugin"
+
+    # Settings fields rendered by the UI and persisted by the backend
+    fields = [
+        {"id": "enabled", "label": "Enabled", "type": "boolean", "default": True},
+        {"id": "limit", "label": "Item limit", "type": "number", "default": 5},
+        {"id": "mode", "label": "Mode", "type": "select", "default": "safe",
+         "options": [
+            {"value": "safe", "label": "Safe"},
+            {"value": "fast", "label": "Fast"},
+         ]},
+        {"id": "note", "label": "Note", "type": "string", "default": ""},
+    ]
+
+    # Actions appear as buttons. Clicking one calls run(action, params, context)
+    actions = [
+        {
+            "id": "do_work",
+            "label": "Do Work",
+            "description": "Process items",
+            "button_label": "Run Job",
+            "button_variant": "filled",
+            "button_color": "blue",
+        },
+    ]
+
+    def run(self, action: str, params: dict, context: dict):
+        settings = context.get("settings", {})
+        logger = context.get("logger")
+
+        if action == "do_work":
+            limit = int(settings.get("limit", 5))
+            mode = settings.get("mode", "safe")
+            logger.info(f"My Plugin running with limit={limit}, mode={mode}")
+            # Do a small amount of work here. Schedule Celery tasks for heavy work.
+            return {"status": "ok", "processed": limit, "mode": mode}
+
+        return {"status": "error", "message": f"Unknown action {action}"}
+```
+
+3) Open the Plugins page in the UI, click the refresh icon to reload discovery, then configure and run your plugin.
+
+---
+
+## Where Plugins Live
+
+- Default directory: `/app/data/plugins` inside the container.
+- Override with env var: `DISPATCHARR_PLUGINS_DIR`.
+- Each plugin is a directory containing either:
+  - `plugin.py` exporting a `Plugin` class, or
+  - a Python package (`__init__.py`) exporting a `Plugin` class.
+- New standard: include a `plugin.json` manifest alongside your code for safe metadata discovery.
+- Optional: include `logo.png` next to `plugin.py` to show a logo in the UI.
+
+The directory name (lowercased, spaces as `_`) is used as the registry key. Plugins are imported under a safe internal package name; if the folder name is a valid identifier (and not reserved), it is also registered as an alias for convenience.
+
+---
+
+## Discovery & Lifecycle
+
+- Discovery runs at server startup and on-demand when:
+  - Fetching the plugins list from the UI
+  - Hitting `POST /api/plugins/plugins/reload/`
+- The loader reads `plugin.json` for metadata without executing plugin code.
+- Plugin code is only imported and instantiated when the plugin is enabled.
+- Metadata (name, version, description) and a per-plugin settings JSON are stored in the DB.
+
+Backend code:
+- Loader: `apps/plugins/loader.py`
+- API Views: `apps/plugins/api_views.py`
+- API URLs: `apps/plugins/api_urls.py`
+- Model: `apps/plugins/models.py` (stores `enabled` flag and `settings` per plugin)
+
+---
+
+## Plugin Manifest (`plugin.json`)
+
+`plugin.json` lets Dispatcharr list your plugin safely without executing code. It should live next to `plugin.py`.
+
+Example:
+```
+{
+  "name": "My Plugin",
+  "version": "1.2.3",
+  "description": "Does something useful",
+  "author": "Acme Labs",
+  "help_url": "https://example.com/docs/my-plugin",
+  "fields": [
+    { "id": "limit", "label": "Item limit", "type": "number", "default": 5 }
+  ],
+  "actions": [
+    {
+      "id": "do_work",
+      "label": "Do Work",
+      "description": "Process items",
+      "button_label": "Run Job",
+      "button_variant": "filled",
+      "button_color": "blue"
+    }
+  ]
+}
+```
+
+Notes:
+- `author` and `help_url` are optional. If provided, the UI shows “By {author}” and a Docs link.
+- If your plugin includes a `logo.png` file next to `plugin.py`, it will be shown on the plugin card.
+
+If `plugin.json` is missing or invalid, the plugin is treated as **legacy**:
+- The name is inferred from the folder name.
+- `logo.png` still displays if present.
+- The UI shows a warning asking the developer to upgrade to the new standard.
+
+---
+
+## Plugin Interface
+
+Export a `Plugin` class. Supported attributes and behavior:
+
+- `name` (str): Human-readable name.
+- `version` (str): Semantic version string.
+- `description` (str): Short description.
+- `author` (str, optional): Author or team name shown on the card.
+- `help_url` (str, optional): Docs/support link shown on the card.
+- `fields` (list): Settings schema used by the UI to render controls.
+- `actions` (list): Available actions; the UI renders a button for each (defaults to Run).
+- `run(action, params, context)` (callable): Invoked when a user clicks an action.
+- `stop(context)` (optional callable): Invoked when the plugin is disabled, deleted, or reloaded so you can gracefully shut down any processes you started. If `stop()` is not defined but you have an action with id `stop`, Dispatcharr will call `run("stop", {}, context)` as a fallback.
+
+### Settings Schema
+Supported field `type`s:
+- `boolean`
+- `number`
+- `string` (single-line text)
+- `text` (multi-line textarea)
+- `select` (requires `options`: `[{"value": ..., "label": ...}, ...]`)
+- `info` (display-only text; useful for headings or notes)
+
+Common field keys:
+- `id` (str): Settings key.
+- `label` (str): Label shown in the UI.
+- `type` (str): One of above.
+- `default` (any): Default value used until saved.
+- `help_text` / `description` (str, optional): Shown under the control.
+- `placeholder` (str, optional): Placeholder text for inputs.
+- `input_type` (str, optional): For `string` fields, set to `"password"` to mask input.
+- `options` (list, for select): List of `{value, label}`.
+
+Notes:
+- For `info` fields, you can use `description`/`help_text` (or `value`) to show the text.
+
+The UI automatically renders settings and persists them. The backend stores settings in `PluginConfig.settings`.
+
+### Example: stop() Hook
+```
+import signal
+
+class Plugin:
+    name = "Example Plugin"
+    version = "1.0.0"
+    description = "Shows how to shut down gracefully."
+
+    def run(self, action: str, params: dict, context: dict):
+        # Start a subprocess or background task here and store its PID.
+        # Example: save pid in /data or in your own module-level variable.
+        return {"status": "ok"}
+
+    def stop(self, context: dict):
+        logger = context.get("logger")
+        pid = self._read_pid()  # your helper
+        if pid:
+            try:
+                os.kill(pid, signal.SIGTERM)
+                logger.info("Stopped process %s", pid)
+            except Exception:
+                logger.exception("Failed to stop process %s", pid)
+```
+
+Read settings in `run` via `context["settings"]`.
+
+### Actions
+Each action is a dict:
+- `id` (str): Unique action id.
+- `label` (str): Action label.
+- `description` (str, optional): Helper text.
+- `button_label` (str, optional): Button text (defaults to “Run”).
+- `button_variant` (str, optional): Button style (Mantine variants like `filled`, `outline`, `subtle`).
+- `button_color` (str, optional): Button color (e.g., `red`, `blue`, `orange`).
+
+Clicking an action calls your plugin’s `run(action, params, context)` and shows a notification with the result or error.
+
+### Action Confirmation (Modal)
+Developers can request a confirmation modal per action using the `confirm` key on the action. Options:
+
+- Boolean: `confirm: true` will show a default confirmation modal.
+- Object: `confirm: { required: true, title: '...', message: '...' }` to customize the modal title and message.
+
+Example:
+```
+actions = [
+    {
+        "id": "danger_run",
+        "label": "Do Something Risky",
+        "description": "Runs a job that affects many records.",
+        "confirm": { "required": true, "title": "Proceed?", "message": "This will modify many records." },
+    }
+]
+```
+
+---
+
+## Accessing Dispatcharr APIs from Plugins
+
+Plugins are server-side Python code running within the Django application. You can:
+
+- Import models and run queries/updates:
+  ```
+  from apps.m3u.models import M3UAccount
+  from apps.epg.models import EPGSource
+  from apps.channels.models import Channel
+  from core.models import CoreSettings
+  ```
+
+- Dispatch Celery tasks for heavy work (recommended):
+  ```
+  from apps.m3u.tasks import refresh_m3u_accounts            # apps/m3u/tasks.py
+  from apps.epg.tasks import refresh_all_epg_data            # apps/epg/tasks.py
+
+  refresh_m3u_accounts.delay()
+  refresh_all_epg_data.delay()
+  ```
+
+- Send WebSocket updates:
+  ```
+  from core.utils import send_websocket_update
+  send_websocket_update('updates', 'update', {"type": "plugin", "plugin": "my_plugin", "message": "Done"})
+  ```
+
+- Use transactions:
+  ```
+  from django.db import transaction
+  with transaction.atomic():
+      # bulk updates here
+      ...
+  ```
+
+- Log via provided context or standard logging:
+  ```
+  def run(self, action, params, context):
+      logger = context.get("logger")  # already configured
+      logger.info("running action %s", action)
+  ```
+
+Prefer Celery tasks (`.delay()`) to keep `run` fast and non-blocking.
+
+### Important: Don’t Ask Users for URL/User/Password
+Dispatcharr plugins run **inside** the Dispatcharr backend process. That means they already have direct access to the app’s models, tasks, and internal utilities.  
+Plugins **should not** ask users for “Dispatcharr URL”, “Admin Username”, or “Admin Password” just to call the API. That is unnecessary and unsafe because:
+
+- It encourages users to enter privileged credentials.
+- Malicious plugins could exfiltrate credentials.
+- It duplicates access that plugins already have internally.
+
+If you are writing a plugin, **use internal Python APIs** (models/tasks/utils) instead of making HTTP calls with user credentials.
+
+### When You Do Need HTTP
+In rare cases you may need to call a Dispatcharr HTTP endpoint (for example, to reuse an existing API response serializer). In that case:
+
+1. **Do not ask the user for credentials.**  
+   Use the backend’s internal access where possible.
+
+2. Prefer **local/internal URLs** (never user-provided):
+   - Docker: `http://web:9191` (service name inside the container network)
+   - Dev: `http://127.0.0.1:5656`
+
+3. Use Django helpers when building URLs:
+   ```
+   from django.urls import reverse
+   path = reverse("api:channels:list")  # example name
+   url = f"http://127.0.0.1:5656{path}"
+   ```
+
+4. Use a short timeout and robust error handling:
+   ```
+   import requests
+   resp = requests.get(url, timeout=10)
+   resp.raise_for_status()
+   data = resp.json()
+   ```
+
+### Examples: Preferred Internal Access (No HTTP, No Credentials)
+
+**Example 1: List channels directly from the DB**
+```
+from apps.channels.models import Channel
+
+channels = Channel.objects.all().values("id", "name", "number")[:50]
+return {"status": "ok", "channels": list(channels)}
+```
+
+**Example 2: Kick off an existing refresh task**
+```
+from apps.m3u.tasks import refresh_m3u_accounts
+from apps.epg.tasks import refresh_all_epg_data
+
+refresh_m3u_accounts.delay()
+refresh_all_epg_data.delay()
+return {"status": "queued"}
+```
+
+**Example 3: Send a WebSocket update to the UI**
+```
+from core.utils import send_websocket_update
+
+send_websocket_update(
+    "updates",
+    "update",
+    {"type": "plugin", "plugin": "my_plugin", "message": "Refresh queued"}
+)
+```
+
+### Example: HTTP Access (Only If You Must)
+
+**Find the endpoint**
+- Use `reverse()` with the named route when possible.
+- If you don’t know the route name, inspect `apps/*/api_urls.py` or Django’s URL config to find it.
+
+```
+from django.urls import reverse
+import requests
+
+path = reverse("api:channels:list")  # named route from apps/channels/api_urls.py
+url = f"http://127.0.0.1:5656{path}"
+
+resp = requests.get(url, timeout=10)
+resp.raise_for_status()
+data = resp.json()
+```
+
+### How Developers Find the API
+
+1. **Prefer internal models/tasks** (best and safest).
+2. **Check `apps/*/api_urls.py`** for named routes and endpoint patterns.
+   - Example: `apps/channels/api_urls.py` for channel endpoints.
+3. **Find the view** referenced in the URL config to see required params.
+   - Example: `apps/channels/api_views.py` or `apps/epg/api_views.py`.
+4. **Use `reverse()`** with the named route to build the path.
+   - This avoids hardcoding paths and keeps plugins compatible if URLs change.
+5. **Only use internal hostnames** (never user-provided URL).
+
+### What Plugins Can Access
+Because plugins run inside the server process, they can:
+- Read and write database models (same permissions as the app)
+- Invoke Celery tasks
+- Send websocket updates
+- Read configuration and settings
+
+Treat plugins as **trusted server code** and avoid exposing sensitive data in plugin settings or logs.
+
+---
+
+## REST Endpoints (for UI and tooling)
+
+- List plugins: `GET /api/plugins/plugins/`
+  - Response: `{ "plugins": [{ key, name, version, description, enabled, fields, settings, actions }, ...] }`
+- Reload discovery: `POST /api/plugins/plugins/reload/`
+- Import plugin: `POST /api/plugins/plugins/import/` with form-data file field `file`
+- Update settings: `POST /api/plugins/plugins/<key>/settings/` with `{"settings": {...}}`
+- Run action: `POST /api/plugins/plugins/<key>/run/` with `{"action": "id", "params": {...}}`
+- Enable/disable: `POST /api/plugins/plugins/<key>/enabled/` with `{"enabled": true|false}`
+
+Notes:
+- When disabled, a plugin cannot run actions; backend returns HTTP 403.
+
+---
+
+## Importing Plugins
+
+- In the UI, click the Import button on the Plugins page and upload a `.zip` containing a plugin folder.
+- The archive should contain either `plugin.py` or a Python package (`__init__.py`).
+- Include `plugin.json` in the plugin folder to provide metadata without executing code.
+- On success, the UI shows the plugin name/description and lets you enable it immediately (plugins are disabled by default).
+  - If `plugin.json` is missing, the plugin is marked as legacy and the UI will show a warning.
+
+---
+
+## Enabling / Disabling Plugins
+
+- Each plugin has a persisted `enabled` flag (default: disabled) and `ever_enabled` flag in the DB (`apps/plugins/models.py`).
+- New plugins are disabled by default and require an explicit enable.
+- The first time a plugin is enabled, the UI shows a trust warning modal explaining that plugins can run arbitrary server-side code.
+- The Plugins page shows a toggle in the card header. Turning it off dims the card and disables the Run button.
+- Backend enforcement: Attempts to run an action for a disabled plugin return HTTP 403.
+- Dispatcharr will not import or execute plugin code unless the plugin is enabled.
+
+---
+
+## Example: Refresh All Sources Plugin
+
+Path: `data/plugins/refresh_all/plugin.py`
+
+```
+class Plugin:
+    name = "Refresh All Sources"
+    version = "1.0.0"
+    description = "Force refresh all M3U accounts and EPG sources."
+
+    fields = [
+        {"id": "confirm", "label": "Require confirmation", "type": "boolean", "default": True,
+         "help_text": "If enabled, the UI should ask before running."}
+    ]
+
+    actions = [
+        {"id": "refresh_all", "label": "Refresh All M3Us and EPGs",
+         "description": "Queues background refresh for all active M3U accounts and EPG sources."}
+    ]
+
+    def run(self, action: str, params: dict, context: dict):
+        if action == "refresh_all":
+            from apps.m3u.tasks import refresh_m3u_accounts
+            from apps.epg.tasks import refresh_all_epg_data
+            refresh_m3u_accounts.delay()
+            refresh_all_epg_data.delay()
+            return {"status": "queued", "message": "Refresh jobs queued"}
+        return {"status": "error", "message": f"Unknown action: {action}"}
+```
+
+---
+
+## Best Practices
+
+- Keep `run` short and schedule heavy operations via Celery tasks.
+- Validate and sanitize `params` received from the UI.
+- Use database transactions for bulk or related updates.
+- Log actionable messages for troubleshooting.
+- Only write files under `/data` or `/app/data` paths.
+- Treat plugins as trusted code: they run with full app permissions.
+
+---
+
+## Troubleshooting
+
+- Plugin not listed: ensure the folder exists and contains `plugin.py` with a `Plugin` class.
+- Import errors: ensure the folder contains `plugin.py` or a package `__init__.py`. Folder names with spaces or dashes are supported; if you need to import by folder name inside your plugin, use a valid Python identifier.
+- No confirmation: include a boolean field with `id: "confirm"` and set it to true or default true.
+- HTTP 403 on run: the plugin is disabled; enable it from the toggle or via the `enabled/` endpoint.
+
+---
+
+## Contributing
+
+- Keep dependencies minimal. Vendoring small helpers into the plugin folder is acceptable.
+- Use the existing task and model APIs where possible; propose extensions if you need new capabilities.
+
+---
+
+## Internals Reference
+
+- Loader: `apps/plugins/loader.py`
+- API Views: `apps/plugins/api_views.py`
+- API URLs: `apps/plugins/api_urls.py`
+- Model: `apps/plugins/models.py`
+- Frontend page: `frontend/src/pages/Plugins.jsx`
+- Sidebar entry: `frontend/src/components/Sidebar.jsx`

README.md

@@ -0,0 +1,179 @@
+# 🎬 Dispatcharr — Your Ultimate IPTV & Stream Management Companion
+
+<p align="center">
+  <img src="https://github.com/Dispatcharr/Dispatcharr/blob/main/frontend/src/images/logo.png?raw=true" height="200" alt="Dispatcharr Logo" />
+</p>
+
+---
+
+## 📖 What is Dispatcharr?
+
+Dispatcharr (pronounced like "dispatcher") is an **open-source powerhouse** for managing IPTV streams, EPG data, and VOD content with elegance and control.\
+Born from necessity and built with passion, it started as a personal project by **[OkinawaBoss](https://github.com/OkinawaBoss)** and evolved with contributions from legends like **[dekzter](https://github.com/dekzter)**, **[SergeantPanda](https://github.com/SergeantPanda)** and **Bucatini**.
+
+> Think of Dispatcharr as the \*arr family's IPTV cousin — simple, smart, and designed for streamers who want reliability and flexibility.
+
+---
+
+## 🎯 What Can I Do With Dispatcharr?
+
+Dispatcharr empowers you with complete IPTV control. Here are some real-world scenarios:
+
+💡 **Consolidate Multiple IPTV Sources**\
+Combine streams from multiple providers into a single interface. Manage, filter, and organize thousands of channels with ease.
+
+📺 **Integrate with Media Centers**\
+Use HDHomeRun emulation to add virtual tuners to **Plex**, **Emby**, or **Jellyfin**. They'll discover Dispatcharr as a live TV source and can record programs directly to their own DVR libraries.
+
+📡 **Create a Personal TV Ecosystem**\
+Merge live TV channels with custom EPG guides. Generate XMLTV schedules or use auto-matching to align channels with existing program data. Export as M3U, Xtream Codes API, or HDHomeRun device.
+
+🔧 **Transcode & Optimize Streams**\
+Configure output profiles with FFmpeg transcoding to optimize streams for different clients — reduce bandwidth, standardize formats, or add audio normalization.
+
+🔐 **Centralize VPN Access**\
+Run Dispatcharr through a VPN container (like Gluetun) so all streams route through a single VPN connection. Your clients access geo-blocked content without needing individual VPNs, reducing bandwidth overhead and simplifying network management.
+
+🚀 **Monitor & Manage in Real-Time**\
+Track active streams, client connections, and bandwidth usage with live statistics. Monitor buffering events and stream quality. Automatic failover keeps viewers connected when streams fail—seamlessly switching to backup sources without interruption.
+
+👥 **Share Access Safely**\
+Create multiple user accounts with granular permissions. Share streams via M3U playlists or Xtream Codes API while controlling which users access which channels, profiles, or features. Network-based access restrictions available for additional security.
+
+🔌 **Extend with Plugins**\
+Build custom integrations using Dispatcharr's robust plugin system. Automate tasks, connect to external services, or add entirely new workflows.
+
+---
+
+## ✨ Why You'll Love Dispatcharr
+
+✅ **Stream Proxy & Relay** — Intercept and proxy IPTV streams with real-time client management\
+✅ **M3U & Xtream Codes** — Import, filter, and organize playlists with multiple backend support\
+✅ **EPG Matching & Generation** — Auto-match EPG to channels or generate custom TV guides\
+✅ **Video on Demand** — Stream movies and TV series with rich metadata and IMDB/TMDB integration\
+✅ **Multi-Format Output** — Export as M3U, XMLTV EPG, Xtream Codes API, or HDHomeRun device\
+✅ **Real-Time Monitoring** — Live connection stats, bandwidth tracking, and automatic failover\
+✅ **Stream Profiles** — Configure different stream profiles for various clients and bandwidth requirements\
+✅ **Flexible Streaming Backends** — VLC, FFmpeg, Streamlink, or custom backends for transcoding and streaming\
+✅ **Multi-User & Access Control** — Granular permissions and network-based access restrictions\
+✅ **Plugin System** — Extend functionality with custom plugins for automation and integrations\
+✅ **Fully Self-Hosted** — Total control, no third-party dependencies
+
+---
+
+# Screenshots
+
+<div align="center">
+  <img src="docs/images/channels.png" alt="Channels" width="750"/>
+  <img src="docs/images/guide.png" alt="TV Guide" width="750"/>
+  <img src="docs/images/stats.png" alt="Stats & Monitoring" width="750"/>
+  <img src="docs/images/m3u-epg-manager.png" alt="M3U & EPG Manager" width="750"/>
+  <img src="docs/images/vod-library.png" alt="VOD Library" width="750"/>
+  <img src="docs/images/settings.png" alt="Settings" width="750"/>
+</div>
+
+---
+
+## 🛠️ Troubleshooting & Help
+
+- **General help?** Visit [Dispatcharr Docs](https://dispatcharr.github.io/Dispatcharr-Docs/)
+- **Community support?** Join our [Discord](https://discord.gg/Sp45V5BcxU)
+
+---
+
+## 🚀 Get Started in Minutes
+
+### 🐳 Quick Start with Docker (Recommended)
+
+```bash
+docker pull ghcr.io/dispatcharr/dispatcharr:latest
+docker run -d \
+  -p 9191:9191 \
+  --name dispatcharr \
+  -v dispatcharr_data:/data \
+  ghcr.io/dispatcharr/dispatcharr:latest
+```
+
+> Customize ports and volumes to fit your setup.
+
+---
+
+### 🐋 Docker Compose Options
+
+| Use Case                    | File                                                    | Description                                                                                                   |
+| --------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| **All-in-One Deployment**   | [docker-compose.aio.yml](docker/docker-compose.aio.yml) | ⭐ Recommended! A simple, all-in-one solution — everything runs in a single container for quick setup.        |
+| **Modular Deployment**      | [docker-compose.yml](docker/docker-compose.yml)         | Separate containers for Dispatcharr, Celery, Redis, and Postgres — perfect if you want more granular control. |
+| **Development Environment** | [docker-compose.dev.yml](docker/docker-compose.dev.yml) | Developer-friendly setup with pre-configured ports and settings for contributing and testing.                 |
+
+---
+
+### 🛠️ Building from Source
+
+> ⚠️ **Warning**: Not officially supported — but if you're here, you know what you're doing!
+
+If you are running a Debian-based OS, use the `debian_install.sh` script. For other OS, contribute a script and we’ll add it!
+
+---
+
+## 🤝 Want to Contribute?
+
+We welcome **PRs, issues, ideas, and suggestions**!
+
+- Prior to contributing, please read the [CONTRIBUTING.md](https://github.com/Dispatcharr/Dispatcharr/blob/main/CONTRIBUTING.md)
+
+> Whether it's writing docs, squashing bugs, or building new features, your contribution matters! 🙋
+
+---
+
+## 📚 Documentation & Roadmap
+
+- 📖 **Documentation:** [Dispatcharr Docs](https://dispatcharr.github.io/Dispatcharr-Docs/)
+
+**Upcoming Features (in no particular order):**
+
+- 🎬 **VOD Management Enhancements** — Granular metadata control and cleanup of unwanted VOD content
+- 📁 **Media Library** — Import local files and serve them over XC API
+- 👥 **Enhanced User Management** — Customizable XC API output per user account
+- 🔄 **Output Stream Profiles** — Different clients with different stream profiles (bandwidth control, quality tiers)
+- 🔌 **Fallback Videos** — Automatic fallback content when channels are unavailable
+
+---
+
+## ❤️ Shoutouts
+
+A huge thank you to all the incredible open-source projects and libraries that power Dispatcharr. We stand on the shoulders of giants!
+
+---
+
+## ✉️ Connect With Us
+
+Have a question? Want to suggest a feature? Just want to say hi?\
+➡️ **[Open an issue](https://github.com/Dispatcharr/Dispatcharr/issues)** or reach out on [Discord](https://discord.gg/Sp45V5BcxU).
+
+---
+
+## 💖 Support Dispatcharr
+
+[![Dispatcharr Open Collective](https://opencollective.com/dispatcharr/tiers/badge.svg)](https://opencollective.com/dispatcharr/contribute)
+
+Open Collective provides a transparent way for anyone who finds value in Dispatcharr to support things like:
+• Infrastructure costs (Domains, Servers, etc.)
+• Apple Developer Program and Google Play Developer accounts
+• Helping contributors dedicate more time to improving the project
+
+Support is completely optional, and Dispatcharr will always remain free and open-source.
+
+[Contribute here](https://opencollective.com/dispatcharr/contribute)
+
+---
+
+## ⚖️ License & Legal
+
+Dispatcharr is licensed under **GNU AGPL v3.0**: For full license details, see [LICENSE](https://www.gnu.org/licenses/agpl-3.0.html).
+
+Dispatcharr is a trademark of the Dispatcharr project. Use of the Dispatcharr name or logo requires permission from the maintainers.
+
+---
+
+### 🚀 _Happy Streaming! The Dispatcharr Team_

apps/accounts/admin.py

@@ -0,0 +1,16 @@
+from django.contrib import admin
+from django.contrib.auth.admin import UserAdmin, GroupAdmin
+from django.contrib.auth.models import Group
+from .models import User
+
+@admin.register(User)
+class CustomUserAdmin(UserAdmin):
+    fieldsets = (
+        (None, {'fields': ('username', 'password', 'avatar_config', 'groups')}),
+        ('Permissions', {'fields': ('is_staff', 'is_superuser', 'user_permissions')}),
+        ('Important dates', {'fields': ('last_login', 'date_joined')}),
+    )
+
+# Unregister default Group admin and re-register it.
+admin.site.unregister(Group)
+admin.site.register(Group, GroupAdmin)

apps/accounts/api_urls.py

@@ -0,0 +1,42 @@
+from django.urls import path, include
+from rest_framework.routers import DefaultRouter
+from .api_views import (
+    AuthViewSet,
+    UserViewSet,
+    GroupViewSet,
+    APIKeyViewSet,
+    TokenObtainPairView,
+    TokenRefreshView,
+    list_permissions,
+    initialize_superuser,
+)
+from rest_framework_simplejwt import views as jwt_views
+
+app_name = "accounts"
+
+# 🔹 Register ViewSets with a Router
+router = DefaultRouter()
+router.register(r"users", UserViewSet, basename="user")
+router.register(r"groups", GroupViewSet, basename="group")
+router.register(r"api-keys", APIKeyViewSet, basename="api-key")
+
+# 🔹 Custom Authentication Endpoints
+auth_view = AuthViewSet.as_view({"post": "login"})
+
+logout_view = AuthViewSet.as_view({"post": "logout"})
+
+# 🔹 Define API URL patterns
+urlpatterns = [
+    # Authentication
+    path("auth/login/", auth_view, name="user-login"),
+    path("auth/logout/", logout_view, name="user-logout"),
+    # Superuser API
+    path("initialize-superuser/", initialize_superuser, name="initialize_superuser"),
+    # Permissions API
+    path("permissions/", list_permissions, name="list-permissions"),
+    path("token/", TokenObtainPairView.as_view(), name="token_obtain_pair"),
+    path("token/refresh/", TokenRefreshView.as_view(), name="token_refresh"),
+]
+
+# 🔹 Include ViewSet routes
+urlpatterns += router.urls

apps/accounts/api_views.py

@@ -0,0 +1,366 @@
+from django.contrib.auth import authenticate, login, logout
+import logging
+from django.contrib.auth.models import Group, Permission
+from django.http import JsonResponse, HttpResponse
+from django.views.decorators.csrf import csrf_exempt
+from rest_framework.decorators import api_view, permission_classes, action
+from rest_framework.response import Response
+from rest_framework import viewsets, status, serializers
+from rest_framework.throttling import AnonRateThrottle
+from drf_spectacular.utils import extend_schema, OpenApiParameter, inline_serializer
+from drf_spectacular.types import OpenApiTypes
+import json
+import secrets
+from .permissions import IsAdmin, Authenticated
+from dispatcharr.utils import network_access_allowed
+
+from .models import User
+from .serializers import UserSerializer, GroupSerializer, PermissionSerializer
+from rest_framework_simplejwt.views import TokenObtainPairView, TokenRefreshView
+
+logger = logging.getLogger(__name__)
+
+
+class LoginRateThrottle(AnonRateThrottle):
+    scope = "login"
+
+
+class TokenObtainPairView(TokenObtainPairView):
+    throttle_classes = [LoginRateThrottle]
+
+    def post(self, request, *args, **kwargs):
+        if not network_access_allowed(request, "UI"):
+            # Log blocked login attempt due to network restrictions
+            from core.utils import log_system_event
+            username = request.data.get("username", 'unknown')
+            client_ip = request.META.get('REMOTE_ADDR', 'unknown')
+            user_agent = request.META.get('HTTP_USER_AGENT', 'unknown')
+            logger.info(f"Login blocked by network policy: user={username} ip={client_ip} ua={user_agent}")
+            log_system_event(
+                event_type='login_failed',
+                user=username,
+                client_ip=client_ip,
+                user_agent=user_agent,
+                reason='Network access denied',
+            )
+            return Response({"error": "Forbidden"}, status=status.HTTP_403_FORBIDDEN)
+
+        # Get the response from the parent class first
+        username = request.data.get("username")
+
+        # Log login attempt
+        from core.utils import log_system_event
+        client_ip = request.META.get('REMOTE_ADDR', 'unknown')
+        user_agent = request.META.get('HTTP_USER_AGENT', 'unknown')
+
+        try:
+            logger.debug(f"Attempting JWT login for user={username}")
+            response = super().post(request, *args, **kwargs)
+
+            # If login was successful, update last_login and log success
+            if response.status_code == 200:
+                if username:
+                    from django.utils import timezone
+                    try:
+                        user = User.objects.get(username=username)
+                        user.last_login = timezone.now()
+                        user.save(update_fields=['last_login'])
+
+                        # Log successful login
+                        log_system_event(
+                            event_type='login_success',
+                            user=username,
+                            client_ip=client_ip,
+                            user_agent=user_agent,
+                        )
+                        logger.info(f"Login success: user={username} ip={client_ip}")
+                    except User.DoesNotExist:
+                        pass  # User doesn't exist, but login somehow succeeded
+            else:
+                # Log failed login attempt
+                log_system_event(
+                    event_type='login_failed',
+                    user=username or 'unknown',
+                    client_ip=client_ip,
+                    user_agent=user_agent,
+                    reason='Invalid credentials',
+                )
+                logger.info(f"Login failed: user={username} ip={client_ip}")
+
+            return response
+
+        except Exception as e:
+            # If parent class raises an exception (e.g., validation error), log failed attempt
+            log_system_event(
+                event_type='login_failed',
+                user=username or 'unknown',
+                client_ip=client_ip,
+                user_agent=user_agent,
+                reason=f'Authentication error: {str(e)[:100]}',
+            )
+            logger.error(f"Login error for user={username}: {e}")
+            raise  # Re-raise the exception to maintain normal error flow
+
+
+class TokenRefreshView(TokenRefreshView):
+    def post(self, request, *args, **kwargs):
+        # Custom logic here
+        if not network_access_allowed(request, "UI"):
+            # Log blocked token refresh attempt due to network restrictions
+            from core.utils import log_system_event
+            client_ip = request.META.get('REMOTE_ADDR', 'unknown')
+            user_agent = request.META.get('HTTP_USER_AGENT', 'unknown')
+            logger.info(f"Token refresh blocked by network policy: ip={client_ip} ua={user_agent}")
+            log_system_event(
+                event_type='login_failed',
+                user='token_refresh',
+                client_ip=client_ip,
+                user_agent=user_agent,
+                reason='Network access denied (token refresh)',
+            )
+            return Response({"error": "Unauthorized"}, status=status.HTTP_403_FORBIDDEN)
+
+        return super().post(request, *args, **kwargs)
+
+
+@csrf_exempt  # In production, consider CSRF protection strategies or ensure this endpoint is only accessible when no superuser exists.
+def initialize_superuser(request):
+    # If an admin-level user already exists, the system is configured
+    if User.objects.filter(user_level__gte=10).exists():
+        return JsonResponse({"superuser_exists": True})
+
+    if request.method == "POST":
+        try:
+            data = json.loads(request.body)
+            username = data.get("username")
+            password = data.get("password")
+            email = data.get("email", "")
+            if not username or not password:
+                return JsonResponse(
+                    {"error": "Username and password are required."}, status=400
+                )
+            # Create the superuser
+            User.objects.create_superuser(
+                username=username, password=password, email=email, user_level=10
+            )
+            return JsonResponse({"superuser_exists": True})
+        except Exception as e:
+            return JsonResponse({"error": str(e)}, status=500)
+    # For GET requests, indicate no superuser exists
+    return JsonResponse({"superuser_exists": False})
+
+
+# 🔹 1) Authentication APIs
+class AuthViewSet(viewsets.ViewSet):
+    """Handles user login and logout"""
+
+    def get_permissions(self):
+        """
+        Login doesn't require auth, but logout does
+        """
+        if self.action == 'logout':
+            return [Authenticated()]
+        return []
+
+    @extend_schema(
+        description="Alias for POST /api/accounts/token/ — returns JWT access and refresh tokens.",
+        request=inline_serializer(
+            name="LoginRequest",
+            fields={
+                "username": serializers.CharField(),
+                "password": serializers.CharField(),
+            },
+        ),
+    )
+    def login(self, request):
+        """Delegates to TokenObtainPairView (JWT login). Throttling, logging, and
+        network access checks are handled there."""
+        view = TokenObtainPairView.as_view()
+        return view(request._request)
+
+    @extend_schema(
+        description="Log out the current user",
+    )
+    def logout(self, request):
+        """Logs out the authenticated user"""
+        # Log logout event before actually logging out
+        from core.utils import log_system_event
+        username = request.user.username if request.user and request.user.is_authenticated else 'unknown'
+        client_ip = request.META.get('REMOTE_ADDR', 'unknown')
+        user_agent = request.META.get('HTTP_USER_AGENT', 'unknown')
+
+        log_system_event(
+            event_type='logout',
+            user=username,
+            client_ip=client_ip,
+            user_agent=user_agent,
+        )
+        logger.info(f"Logout: user={username} ip={client_ip}")
+
+        logout(request)
+        return Response({"message": "Logout successful"})
+
+
+# 🔹 2) User Management APIs
+class UserViewSet(viewsets.ModelViewSet):
+    """Handles CRUD operations for Users"""
+
+    queryset = User.objects.all().prefetch_related('channel_profiles')
+    serializer_class = UserSerializer
+
+    def get_permissions(self):
+        if self.action == "me":
+            return [Authenticated()]
+
+        return [IsAdmin()]
+
+    @extend_schema(
+        description="Retrieve a list of users",
+        responses={200: UserSerializer(many=True)},
+    )
+    def list(self, request, *args, **kwargs):
+        return super().list(request, *args, **kwargs)
+
+    @extend_schema(description="Retrieve a specific user by ID")
+    def retrieve(self, request, *args, **kwargs):
+        return super().retrieve(request, *args, **kwargs)
+
+    @extend_schema(description="Create a new user")
+    def create(self, request, *args, **kwargs):
+        return super().create(request, *args, **kwargs)
+
+    @extend_schema(description="Update a user")
+    def update(self, request, *args, **kwargs):
+        return super().update(request, *args, **kwargs)
+
+    @extend_schema(description="Delete a user")
+    def destroy(self, request, *args, **kwargs):
+        return super().destroy(request, *args, **kwargs)
+
+    @extend_schema(
+        description="Get or update active user information. PATCH updates custom_properties with merge semantics.",
+        methods=["GET", "PATCH"],
+    )
+    @action(detail=False, methods=["get", "patch"], url_path="me")
+    def me(self, request):
+        user = request.user
+        if request.method == "PATCH":
+            ALLOWED_FIELDS = {"custom_properties", "first_name", "last_name", "email", "password"}
+            disallowed = set(request.data.keys()) - ALLOWED_FIELDS
+
+            for key in disallowed:
+                request.data.pop(key, None)
+
+            # Strip admin-managed keys from custom_properties so users cannot
+            # set their own XC credentials via this endpoint.
+            ADMIN_ONLY_PROPS = {"xc_password"}
+            cp = request.data.get("custom_properties")
+            if isinstance(cp, dict):
+                for key in ADMIN_ONLY_PROPS:
+                    cp.pop(key, None)
+
+            serializer = UserSerializer(user, data=request.data, partial=True)
+            serializer.is_valid(raise_exception=True)
+            serializer.save()
+            return Response(serializer.data)
+        serializer = UserSerializer(user)
+        return Response(serializer.data)
+
+
+# 🔹 3) Group Management APIs
+class GroupViewSet(viewsets.ModelViewSet):
+    """Handles CRUD operations for Groups"""
+
+    queryset = Group.objects.all()
+    serializer_class = GroupSerializer
+    permission_classes = [Authenticated]
+
+    @extend_schema(
+        description="Retrieve a list of groups",
+        responses={200: GroupSerializer(many=True)},
+    )
+    def list(self, request, *args, **kwargs):
+        return super().list(request, *args, **kwargs)
+
+    @extend_schema(description="Retrieve a specific group by ID")
+    def retrieve(self, request, *args, **kwargs):
+        return super().retrieve(request, *args, **kwargs)
+
+    @extend_schema(description="Create a new group")
+    def create(self, request, *args, **kwargs):
+        return super().create(request, *args, **kwargs)
+
+    @extend_schema(description="Update a group")
+    def update(self, request, *args, **kwargs):
+        return super().update(request, *args, **kwargs)
+
+    @extend_schema(description="Delete a group")
+    def destroy(self, request, *args, **kwargs):
+        return super().destroy(request, *args, **kwargs)
+
+
+# API Key management
+class APIKeyViewSet(viewsets.ViewSet):
+    permission_classes = [Authenticated]
+
+    def list(self, request):
+        user = request.user
+        return Response({"key": user.api_key})
+
+    @action(detail=False, methods=["post"], url_path="generate")
+    def generate(self, request):
+        target_user = request.user
+        user_id = request.data.get("user_id")
+
+        if user_id:
+            from .permissions import IsAdmin
+
+            if not IsAdmin().has_permission(request, self):
+                return Response({"detail": "Not allowed to create keys for other users."}, status=status.HTTP_403_FORBIDDEN)
+
+            try:
+                target_user = User.objects.get(id=int(user_id))
+            except Exception:
+                return Response({"detail": "User not found."}, status=status.HTTP_404_NOT_FOUND)
+
+        raw = secrets.token_urlsafe(40)
+        target_user.api_key = raw
+        target_user.save(update_fields=["api_key"])
+
+        user_data = UserSerializer(target_user).data
+        return Response({"key": raw, "user": user_data}, status=status.HTTP_201_CREATED)
+
+    @action(detail=False, methods=["post"], url_path="revoke")
+    def revoke(self, request):
+        target_user = request.user
+        user_id = request.data.get("user_id")
+
+        if user_id:
+            from .permissions import IsAdmin
+
+            if not IsAdmin().has_permission(request, self):
+                return Response({"detail": "Not allowed to revoke keys for other users."}, status=status.HTTP_403_FORBIDDEN)
+
+            try:
+                target_user = User.objects.get(id=int(user_id))
+            except Exception:
+                return Response({"detail": "User not found."}, status=status.HTTP_404_NOT_FOUND)
+
+        target_user.api_key = None
+        target_user.save(update_fields=["api_key"])
+
+        return Response({"success": True})
+
+
+# 🔹 4) Permissions List API
+@extend_schema(
+    description="Retrieve a list of all permissions",
+    responses={200: PermissionSerializer(many=True)},
+)
+@api_view(["GET"])
+@permission_classes([Authenticated])
+def list_permissions(request):
+    """Returns a list of all available permissions"""
+    permissions = Permission.objects.all()
+    serializer = PermissionSerializer(permissions, many=True)
+    return Response(serializer.data)

apps/accounts/apps.py

@@ -0,0 +1,7 @@
+from django.apps import AppConfig
+
+
+class AccountsConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "apps.accounts"
+    verbose_name = "Accounts & Authentication"

apps/accounts/authentication.py

@@ -0,0 +1,86 @@
+from rest_framework import authentication
+from rest_framework import exceptions
+from django.conf import settings
+from drf_spectacular.extensions import OpenApiAuthenticationExtension
+from .models import User
+
+
+class JWTAuthenticationScheme(OpenApiAuthenticationExtension):
+    target_class = "rest_framework_simplejwt.authentication.JWTAuthentication"
+    name = "jwtAuth"
+
+    def get_security_definition(self, auto_schema):
+        return {
+            "type": "http",
+            "scheme": "bearer",
+            "bearerFormat": "JWT",
+            "description": (
+                "JWT Bearer authentication.\n\n"
+                "Obtain a token pair via `POST /api/accounts/token/` using your username and password, "
+                "then paste the **access token** here — Swagger adds the `Bearer ` prefix automatically.\n\n"
+                "Access tokens expire after 30 minutes. Refresh using `POST /api/accounts/token/refresh/`."
+            ),
+        }
+
+
+class ApiKeyAuthenticationScheme(OpenApiAuthenticationExtension):
+    target_class = "apps.accounts.authentication.ApiKeyAuthentication"
+    name = "ApiKeyAuth"
+
+    def get_security_definition(self, auto_schema):
+        return {
+            "type": "apiKey",
+            "in": "header",
+            "name": "X-API-Key",
+            "description": (
+                "API key authentication.\n\n"
+                "Pass your personal API key in the `X-API-Key` request header. "
+                "Keys can be generated via `POST /api/accounts/api-keys/generate/` "
+                "and revoked via `POST /api/accounts/api-keys/revoke/`."
+            ),
+        }
+
+
+class ApiKeyAuthentication(authentication.BaseAuthentication):
+    """
+    Accepts header `Authorization: ApiKey <key>` or `X-API-Key: <key>`.
+    """
+
+    keyword = "ApiKey"
+
+    def authenticate(self, request):
+        # Check X-API-Key header first
+        raw_key = request.META.get("HTTP_X_API_KEY")
+
+        if not raw_key:
+            auth = authentication.get_authorization_header(request).split()
+            if not auth:
+                return None
+
+            if len(auth) != 2:
+                return None
+
+            scheme = auth[0].decode().lower()
+            if scheme != self.keyword.lower():
+                return None
+
+            raw_key = auth[1].decode()
+
+        if not raw_key:
+            return None
+
+        if not raw_key:
+            return None
+
+        try:
+            user = User.objects.get(api_key=raw_key)
+        except User.DoesNotExist:
+            raise exceptions.AuthenticationFailed("Invalid API key")
+
+        if not user.is_active:
+            raise exceptions.AuthenticationFailed("User inactive")
+
+        return (user, None)
+
+    def authenticate_header(self, request):
+        return self.keyword

apps/accounts/forms.py

@@ -0,0 +1,59 @@
+from django import forms
+from django.contrib.auth.forms import UserCreationForm
+from django.contrib.auth.models import Permission
+from django.contrib.auth.models import Group as AuthGroup
+from apps.channels.models import ChannelGroup
+from .models import User
+
+from .models import User
+
+
+class UserRegistrationForm(UserCreationForm):
+    groups = forms.ModelMultipleChoiceField(
+        queryset=AuthGroup.objects.all(),
+        required=False,
+        widget=forms.CheckboxSelectMultiple
+    )
+
+    class Meta:
+        model = User
+        fields = ['username', 'groups', 'password1', 'password2', ]
+
+    def save(self, commit=True):
+        user = super().save(commit=False)
+        if commit:
+            user.save()
+            self.save_m2m()  # Save the many-to-many field data
+        return user
+
+
+
+class GroupForm(forms.ModelForm):
+    permissions = forms.ModelMultipleChoiceField(
+        queryset=Permission.objects.all(),
+        widget=forms.CheckboxSelectMultiple,
+        required=False
+    )
+
+    class Meta:
+        model = AuthGroup
+        fields = ['name', 'permissions']
+
+
+class UserEditForm(forms.ModelForm):
+    auth_groups = forms.ModelMultipleChoiceField(
+        queryset=AuthGroup.objects.all(),
+        widget=forms.CheckboxSelectMultiple,
+        required=False,
+        label="Auth Groups"
+    )
+    channel_groups = forms.ModelMultipleChoiceField(
+        queryset=ChannelGroup.objects.all(),
+        widget=forms.CheckboxSelectMultiple,
+        required=False,
+        label="Channel Groups"
+    )
+
+    class Meta:
+        model = User
+        fields = ['username', 'email', 'auth_groups', 'channel_groups']

apps/accounts/migrations/0001_initial.py

@@ -0,0 +1,47 @@
+# Generated by Django 5.1.6 on 2025-03-05 22:07
+
+import django.contrib.auth.models
+import django.contrib.auth.validators
+import django.utils.timezone
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = [
+        ('auth', '0012_alter_user_first_name_max_length'),
+        ('dispatcharr_channels', '0001_initial'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='User',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('password', models.CharField(max_length=128, verbose_name='password')),
+                ('last_login', models.DateTimeField(blank=True, null=True, verbose_name='last login')),
+                ('is_superuser', models.BooleanField(default=False, help_text='Designates that this user has all permissions without explicitly assigning them.', verbose_name='superuser status')),
+                ('username', models.CharField(error_messages={'unique': 'A user with that username already exists.'}, help_text='Required. 150 characters or fewer. Letters, digits and @/./+/-/_ only.', max_length=150, unique=True, validators=[django.contrib.auth.validators.UnicodeUsernameValidator()], verbose_name='username')),
+                ('first_name', models.CharField(blank=True, max_length=150, verbose_name='first name')),
+                ('last_name', models.CharField(blank=True, max_length=150, verbose_name='last name')),
+                ('email', models.EmailField(blank=True, max_length=254, verbose_name='email address')),
+                ('is_staff', models.BooleanField(default=False, help_text='Designates whether the user can log into this admin site.', verbose_name='staff status')),
+                ('is_active', models.BooleanField(default=True, help_text='Designates whether this user should be treated as active. Unselect this instead of deleting accounts.', verbose_name='active')),
+                ('date_joined', models.DateTimeField(default=django.utils.timezone.now, verbose_name='date joined')),
+                ('avatar_config', models.JSONField(blank=True, default=dict, null=True)),
+                ('channel_groups', models.ManyToManyField(blank=True, related_name='users', to='dispatcharr_channels.channelgroup')),
+                ('groups', models.ManyToManyField(blank=True, help_text='The groups this user belongs to. A user will get all permissions granted to each of their groups.', related_name='user_set', related_query_name='user', to='auth.group', verbose_name='groups')),
+                ('user_permissions', models.ManyToManyField(blank=True, help_text='Specific permissions for this user.', related_name='user_set', related_query_name='user', to='auth.permission', verbose_name='user permissions')),
+            ],
+            options={
+                'verbose_name': 'user',
+                'verbose_name_plural': 'users',
+                'abstract': False,
+            },
+            managers=[
+                ('objects', django.contrib.auth.models.UserManager()),
+            ],
+        ),
+    ]

apps/accounts/migrations/0002_remove_user_channel_groups_user_channel_profiles_and_more.py

@@ -0,0 +1,43 @@
+# Generated by Django 5.1.6 on 2025-05-18 15:47
+
+from django.db import migrations, models
+
+
+def set_user_level_to_10(apps, schema_editor):
+    User = apps.get_model("accounts", "User")
+    User.objects.update(user_level=10)
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("accounts", "0001_initial"),
+        ("dispatcharr_channels", "0021_channel_user_level"),
+    ]
+
+    operations = [
+        migrations.RemoveField(
+            model_name="user",
+            name="channel_groups",
+        ),
+        migrations.AddField(
+            model_name="user",
+            name="channel_profiles",
+            field=models.ManyToManyField(
+                blank=True,
+                related_name="users",
+                to="dispatcharr_channels.channelprofile",
+            ),
+        ),
+        migrations.AddField(
+            model_name="user",
+            name="user_level",
+            field=models.IntegerField(default=0),
+        ),
+        migrations.AddField(
+            model_name="user",
+            name="custom_properties",
+            field=models.TextField(blank=True, null=True),
+        ),
+        migrations.RunPython(set_user_level_to_10),
+    ]

apps/accounts/migrations/0003_alter_user_custom_properties.py

@@ -0,0 +1,18 @@
+# Generated by Django 5.2.4 on 2025-09-02 14:30
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('accounts', '0002_remove_user_channel_groups_user_channel_profiles_and_more'),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name='user',
+            name='custom_properties',
+            field=models.JSONField(blank=True, default=dict, null=True),
+        ),
+    ]

apps/accounts/migrations/0004_user_api_key.py

@@ -0,0 +1,18 @@
+# Generated by Django 5.2.11 on 2026-02-21 18:14
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('accounts', '0003_alter_user_custom_properties'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='user',
+            name='api_key',
+            field=models.CharField(blank=True, db_index=True, max_length=200, null=True),
+        ),
+    ]

apps/accounts/migrations/0005_alter_user_managers.py

@@ -0,0 +1,20 @@
+# Generated by Django 5.2.11 on 2026-02-26 19:24
+
+import apps.accounts.models
+from django.db import migrations
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('accounts', '0004_user_api_key'),
+    ]
+
+    operations = [
+        migrations.AlterModelManagers(
+            name='user',
+            managers=[
+                ('objects', apps.accounts.models.CustomUserManager()),
+            ],
+        ),
+    ]

apps/accounts/migrations/0006_user_stream_limit.py

@@ -0,0 +1,18 @@
+# Generated by Django 5.2.11 on 2026-03-19 13:46
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('accounts', '0005_alter_user_managers'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='user',
+            name='stream_limit',
+            field=models.IntegerField(default=0),
+        ),
+    ]

apps/accounts/models.py

@@ -0,0 +1,48 @@
+# apps/accounts/models.py
+from django.db import models
+from django.contrib.auth.models import AbstractUser, Permission, UserManager
+
+
+class CustomUserManager(UserManager):
+    def create_superuser(self, username, email=None, password=None, **extra_fields):
+        extra_fields.setdefault('user_level', 10)
+        return super().create_superuser(username, email, password, **extra_fields)
+
+
+class User(AbstractUser):
+    objects = CustomUserManager()
+    """
+    Custom user model for Dispatcharr.
+    Inherits from Django's AbstractUser to add additional fields if needed.
+    """
+
+    class UserLevel(models.IntegerChoices):
+        STREAMER = 0, "Streamer"
+        STANDARD = 1, "Standard User"
+        ADMIN = 10, "Admin"
+
+    avatar_config = models.JSONField(default=dict, blank=True, null=True)
+    channel_profiles = models.ManyToManyField(
+        "dispatcharr_channels.ChannelProfile",
+        blank=True,
+        related_name="users",
+    )
+    user_level = models.IntegerField(default=UserLevel.STREAMER)
+    custom_properties = models.JSONField(default=dict, blank=True, null=True)
+    api_key = models.CharField(max_length=200, blank=True, null=True, db_index=True)
+    stream_limit = models.IntegerField(default=0)
+
+    def __str__(self):
+        return self.username
+
+    def get_groups(self):
+        """
+        Returns the groups (roles) the user belongs to.
+        """
+        return self.groups.all()
+
+    def get_permissions(self):
+        """
+        Returns the permissions assigned to the user and their groups.
+        """
+        return self.user_permissions.all() | Permission.objects.filter(group__user=self)

apps/accounts/permissions.py

@@ -0,0 +1,56 @@
+from rest_framework.permissions import IsAuthenticated
+from .models import User
+from dispatcharr.utils import network_access_allowed
+
+
+class Authenticated(IsAuthenticated):
+    def has_permission(self, request, view):
+        is_authenticated = super().has_permission(request, view)
+        network_allowed = network_access_allowed(request, "UI")
+
+        return is_authenticated and network_allowed
+
+
+class IsStandardUser(Authenticated):
+    def has_permission(self, request, view):
+        if not super().has_permission(request, view):
+            return False
+
+        return request.user and request.user.user_level >= User.UserLevel.STANDARD
+
+
+class IsAdmin(Authenticated):
+    def has_permission(self, request, view):
+        if not super().has_permission(request, view):
+            return False
+
+        return request.user.user_level >= 10
+
+
+class IsOwnerOfObject(Authenticated):
+    def has_object_permission(self, request, view, obj):
+        if not super().has_permission(request, view):
+            return False
+
+        is_admin = IsAdmin().has_permission(request, view)
+        is_owner = request.user in obj.users.all()
+
+        return is_admin or is_owner
+
+
+permission_classes_by_action = {
+    "list": [IsStandardUser],
+    "create": [IsAdmin],
+    "retrieve": [IsStandardUser],
+    "update": [IsAdmin],
+    "partial_update": [IsAdmin],
+    "destroy": [IsAdmin],
+}
+
+permission_classes_by_method = {
+    "GET": [IsStandardUser],
+    "POST": [IsAdmin],
+    "PATCH": [IsAdmin],
+    "PUT": [IsAdmin],
+    "DELETE": [IsAdmin],
+}

apps/accounts/serializers.py

@@ -0,0 +1,145 @@
+import json
+
+from rest_framework import serializers
+from django.contrib.auth.models import Group, Permission
+from .models import User
+from apps.channels.models import ChannelProfile
+
+
+# Valid navigation item IDs for validation
+VALID_NAV_ITEM_IDS = {
+    'channels', 'vods', 'sources', 'guide', 'dvr',
+    'stats', 'plugins', 'integrations', 'system', 'settings'
+}
+MAX_CUSTOM_PROPS_SIZE = 10240  # 10KB limit
+
+
+def validate_nav_array(value, field_name):
+    """Validate that a value is an array of valid nav item ID strings."""
+    if not isinstance(value, list):
+        raise serializers.ValidationError(f"{field_name} must be an array")
+    if len(value) > 50:
+        raise serializers.ValidationError(f"{field_name} exceeds maximum length of 50 items")
+    for item in value:
+        if not isinstance(item, str):
+            raise serializers.ValidationError(f"{field_name} items must be strings")
+        if item not in VALID_NAV_ITEM_IDS:
+            raise serializers.ValidationError(f"'{item}' is not a valid navigation item ID")
+
+
+# 🔹 Fix for Permission serialization
+class PermissionSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = Permission
+        fields = ["id", "name", "codename"]
+
+
+# 🔹 Fix for Group serialization
+class GroupSerializer(serializers.ModelSerializer):
+    permissions = serializers.PrimaryKeyRelatedField(
+        many=True, queryset=Permission.objects.all()
+    )  # ✅ Fixes ManyToManyField `_meta` error
+
+    class Meta:
+        model = Group
+        fields = ["id", "name", "permissions"]
+
+
+# 🔹 Fix for User serialization
+class UserSerializer(serializers.ModelSerializer):
+    password = serializers.CharField(write_only=True, required=False)
+    channel_profiles = serializers.PrimaryKeyRelatedField(
+        queryset=ChannelProfile.objects.all(), many=True, required=False
+    )
+    api_key = serializers.CharField(read_only=True, allow_null=True)
+
+    class Meta:
+        model = User
+        fields = [
+            "id",
+            "username",
+            "api_key",
+            "email",
+            "user_level",
+            "password",
+            "channel_profiles",
+            "custom_properties",
+            "avatar_config",
+            "stream_limit",
+            "is_staff",
+            "is_superuser",
+            "last_login",
+            "date_joined",
+            "first_name",
+            "last_name",
+        ]
+
+    def validate_custom_properties(self, value):
+        """Validate custom_properties structure and size."""
+        if value is None:
+            return {}
+        if not isinstance(value, dict):
+            raise serializers.ValidationError("custom_properties must be a dictionary")
+
+        # Size limit check
+        try:
+            if len(json.dumps(value)) > MAX_CUSTOM_PROPS_SIZE:
+                raise serializers.ValidationError(
+                    f"custom_properties exceeds maximum size of {MAX_CUSTOM_PROPS_SIZE} bytes"
+                )
+        except (TypeError, ValueError):
+            raise serializers.ValidationError("custom_properties contains non-serializable data")
+
+        # Validate navOrder if present
+        if 'navOrder' in value:
+            validate_nav_array(value['navOrder'], 'navOrder')
+
+        # Validate hiddenNav if present
+        if 'hiddenNav' in value:
+            validate_nav_array(value['hiddenNav'], 'hiddenNav')
+
+        return value
+
+    def create(self, validated_data):
+        channel_profiles = validated_data.pop("channel_profiles", [])
+
+        user = User(**validated_data)
+        user.set_password(validated_data["password"])
+        user.save()
+
+        user.channel_profiles.set(channel_profiles)
+
+        return user
+
+    def update(self, instance, validated_data):
+        password = validated_data.pop("password", None)
+        channel_profiles = validated_data.pop("channel_profiles", None)
+
+        # Merge custom_properties instead of replacing (prevents data loss)
+        # Strip null values — sending null for a key omits it rather than overwriting with null
+        custom_properties = validated_data.pop("custom_properties", None)
+        if custom_properties is not None:
+            existing = instance.custom_properties or {}
+            cleaned = {k: v for k, v in custom_properties.items() if v is not None}
+            merged = {**existing, **cleaned}
+            # Scrub stale nav IDs so the DB self-heals on next save
+            for nav_field in ('navOrder', 'hiddenNav'):
+                if nav_field in merged and isinstance(merged[nav_field], list):
+                    merged[nav_field] = [
+                        item for item in merged[nav_field]
+                        if item in VALID_NAV_ITEM_IDS
+                    ]
+            instance.custom_properties = merged
+
+        for attr, value in validated_data.items():
+            setattr(instance, attr, value)
+
+        if password:
+            instance.set_password(password)
+
+        instance.save()
+
+        if channel_profiles is not None:
+            instance.channel_profiles.set(channel_profiles)
+
+        return instance

apps/accounts/signals.py

@@ -0,0 +1,15 @@
+# apps/accounts/signals.py
+# Example: automatically create something on user creation
+
+from django.db.models.signals import post_save
+from django.dispatch import receiver
+from .models import User
+
+
+@receiver(post_save, sender=User)
+def handle_new_user(sender, instance, created, **kwargs):
+    if created:
+        # e.g. initialize default avatar config
+        if not instance.avatar_config:
+            instance.avatar_config = {"style": "circle"}
+            instance.save()

apps/accounts/tests.py

@@ -0,0 +1,72 @@
+from django.test import TestCase
+from django.contrib.auth import get_user_model
+from rest_framework.test import APIClient
+
+User = get_user_model()
+
+
+class InitializeSuperuserTests(TestCase):
+    """Tests for the initialize_superuser endpoint"""
+
+    def setUp(self):
+        self.client = APIClient()
+        self.url = "/api/accounts/initialize-superuser/"
+
+    def test_returns_true_when_superuser_exists(self):
+        """Superuser with is_superuser=True should be detected"""
+        User.objects.create_superuser(
+            username="admin", password="testpass123", user_level=10
+        )
+        response = self.client.get(self.url)
+        self.assertEqual(response.status_code, 200)
+        self.assertTrue(response.json()["superuser_exists"])
+
+    def test_returns_true_when_admin_level_user_exists(self):
+        """User with user_level=10 but is_superuser=False should be detected"""
+        user = User.objects.create_user(username="admin", password="testpass123")
+        user.user_level = 10
+        user.is_superuser = False
+        user.save()
+        response = self.client.get(self.url)
+        self.assertEqual(response.status_code, 200)
+        self.assertTrue(response.json()["superuser_exists"])
+
+    def test_returns_false_when_no_admin_exists(self):
+        """No admin or superuser should return false"""
+        # Create a non-admin user
+        User.objects.create_user(username="regular", password="testpass123")
+        response = self.client.get(self.url)
+        self.assertEqual(response.status_code, 200)
+        self.assertFalse(response.json()["superuser_exists"])
+
+    def test_returns_false_when_no_users_exist(self):
+        """Empty database should return false"""
+        response = self.client.get(self.url)
+        self.assertEqual(response.status_code, 200)
+        self.assertFalse(response.json()["superuser_exists"])
+
+    def test_create_superuser_when_none_exists(self):
+        """POST should create superuser when none exists"""
+        response = self.client.post(
+            self.url,
+            {"username": "newadmin", "password": "testpass123", "email": "admin@test.com"},
+            format="json",
+        )
+        self.assertEqual(response.status_code, 200)
+        self.assertTrue(response.json()["superuser_exists"])
+        self.assertTrue(User.objects.filter(username="newadmin", user_level=10).exists())
+
+    def test_cannot_create_superuser_when_admin_exists(self):
+        """POST should fail when an admin-level user already exists"""
+        user = User.objects.create_user(username="existing", password="testpass123")
+        user.user_level = 10
+        user.save()
+        response = self.client.post(
+            self.url,
+            {"username": "newadmin", "password": "testpass123"},
+            format="json",
+        )
+        self.assertEqual(response.status_code, 200)
+        self.assertTrue(response.json()["superuser_exists"])
+        # Should NOT have created a new user
+        self.assertFalse(User.objects.filter(username="newadmin").exists())

apps/accounts/urls.py

@@ -0,0 +1,12 @@
+from django.urls import path
+from django.contrib.auth import views as auth_views
+
+app_name = 'accounts'
+
+urlpatterns = [
+    # Login view using Django's built-in authentication
+    path('login/', auth_views.LoginView.as_view(template_name='login.html'), name='login'),
+    # Logout view using Django's built-in authentication
+    path('logout/', auth_views.LogoutView.as_view(next_page='accounts:login'), name='logout'),
+    # Onetime use superuser account creation
+]

apps/api/urls.py

@@ -0,0 +1,29 @@
+from django.urls import path, include, re_path
+from drf_spectacular.views import SpectacularAPIView, SpectacularSwaggerView, SpectacularRedocView
+
+app_name = 'api'
+
+urlpatterns = [
+    path('accounts/', include(('apps.accounts.api_urls', 'accounts'), namespace='accounts')),
+    path('channels/', include(('apps.channels.api_urls', 'channels'), namespace='channels')),
+    path('epg/', include(('apps.epg.api_urls', 'epg'), namespace='epg')),
+    path('hdhr/', include(('apps.hdhr.api_urls', 'hdhr'), namespace='hdhr')),
+    path('m3u/', include(('apps.m3u.api_urls', 'm3u'), namespace='m3u')),
+    path('core/', include(('core.api_urls', 'core'), namespace='core')),
+    path('plugins/', include(('apps.plugins.api_urls', 'plugins'), namespace='plugins')),
+    path('vod/', include(('apps.vod.api_urls', 'vod'), namespace='vod')),
+    path('backups/', include(('apps.backups.api_urls', 'backups'), namespace='backups')),
+    path('connect/', include(('apps.connect.api_urls', 'connect'), namespace='connect')),
+    # path('output/', include(('apps.output.api_urls', 'output'), namespace='output')),
+    #path('player/', include(('apps.player.api_urls', 'player'), namespace='player')),
+    #path('settings/', include(('apps.settings.api_urls', 'settings'), namespace='settings')),
+    #path('streams/', include(('apps.streams.api_urls', 'streams'), namespace='streams')),
+
+
+
+    # OpenAPI Schema and Documentation (drf-spectacular)
+    path('schema/', SpectacularAPIView.as_view(), name='schema'),
+    re_path(r'^swagger/?$', SpectacularSwaggerView.as_view(url_name='api:schema'), name='swagger-ui'),
+    path('redoc/', SpectacularRedocView.as_view(url_name='api:schema'), name='redoc'),
+    path('swagger.json', SpectacularAPIView.as_view(), name='schema-json'),
+]

apps/backups/api_urls.py

@@ -0,0 +1,18 @@
+from django.urls import path
+
+from . import api_views
+
+app_name = "backups"
+
+urlpatterns = [
+    path("", api_views.list_backups, name="backup-list"),
+    path("create/", api_views.create_backup, name="backup-create"),
+    path("upload/", api_views.upload_backup, name="backup-upload"),
+    path("schedule/", api_views.get_schedule, name="backup-schedule-get"),
+    path("schedule/update/", api_views.update_schedule, name="backup-schedule-update"),
+    path("status/<str:task_id>/", api_views.backup_status, name="backup-status"),
+    path("<str:filename>/download-token/", api_views.get_download_token, name="backup-download-token"),
+    path("<str:filename>/download/", api_views.download_backup, name="backup-download"),
+    path("<str:filename>/delete/", api_views.delete_backup, name="backup-delete"),
+    path("<str:filename>/restore/", api_views.restore_backup, name="backup-restore"),
+]

apps/backups/api_views.py

@@ -0,0 +1,374 @@
+import hashlib
+import hmac
+import logging
+import os
+from pathlib import Path
+
+from celery.result import AsyncResult
+from django.conf import settings
+from django.http import HttpResponse, StreamingHttpResponse, Http404
+from rest_framework import status
+from rest_framework.decorators import api_view, permission_classes, parser_classes
+from rest_framework.permissions import AllowAny
+from apps.accounts.permissions import IsAdmin
+from rest_framework.parsers import MultiPartParser, FormParser
+from rest_framework.response import Response
+from core.utils import safe_upload_path
+
+from . import services
+from .tasks import create_backup_task, restore_backup_task
+from .scheduler import get_schedule_settings, update_schedule_settings
+
+logger = logging.getLogger(__name__)
+
+
+def _generate_task_token(task_id: str) -> str:
+    """Generate a signed token for task status access without auth."""
+    secret = settings.SECRET_KEY.encode()
+    return hmac.new(secret, task_id.encode(), hashlib.sha256).hexdigest()[:32]
+
+
+def _verify_task_token(task_id: str, token: str) -> bool:
+    """Verify a task token is valid."""
+    expected = _generate_task_token(task_id)
+    return hmac.compare_digest(expected, token)
+
+
+@api_view(["GET"])
+@permission_classes([IsAdmin])
+def list_backups(request):
+    """List all available backup files."""
+    try:
+        backups = services.list_backups()
+        return Response(backups, status=status.HTTP_200_OK)
+    except Exception as e:
+        return Response(
+            {"detail": f"Failed to list backups: {str(e)}"},
+            status=status.HTTP_500_INTERNAL_SERVER_ERROR,
+        )
+
+
+@api_view(["POST"])
+@permission_classes([IsAdmin])
+def create_backup(request):
+    """Create a new backup (async via Celery)."""
+    try:
+        task = create_backup_task.delay()
+        return Response(
+            {
+                "detail": "Backup started",
+                "task_id": task.id,
+                "task_token": _generate_task_token(task.id),
+            },
+            status=status.HTTP_202_ACCEPTED,
+        )
+    except Exception as e:
+        return Response(
+            {"detail": f"Failed to start backup: {str(e)}"},
+            status=status.HTTP_500_INTERNAL_SERVER_ERROR,
+        )
+
+
+@api_view(["GET"])
+@permission_classes([AllowAny])
+def backup_status(request, task_id):
+    """Check the status of a backup/restore task.
+
+    Requires either:
+    - Valid admin authentication, OR
+    - Valid task_token query parameter
+    """
+    # Check for token-based auth (for restore when session is invalidated)
+    token = request.query_params.get("token")
+    if token:
+        if not _verify_task_token(task_id, token):
+            return Response(
+                {"detail": "Invalid task token"},
+                status=status.HTTP_403_FORBIDDEN,
+            )
+    else:
+        # Fall back to admin auth check
+        if not request.user.is_authenticated or getattr(request.user, 'user_level', 0) < 10:
+            return Response(
+                {"detail": "Authentication required"},
+                status=status.HTTP_401_UNAUTHORIZED,
+            )
+
+    try:
+        result = AsyncResult(task_id)
+
+        if result.ready():
+            task_result = result.get()
+            if task_result.get("status") == "completed":
+                return Response({
+                    "state": "completed",
+                    "result": task_result,
+                })
+            else:
+                return Response({
+                    "state": "failed",
+                    "error": task_result.get("error", "Unknown error"),
+                })
+        elif result.failed():
+            return Response({
+                "state": "failed",
+                "error": str(result.result),
+            })
+        else:
+            return Response({
+                "state": result.state.lower(),
+            })
+    except Exception as e:
+        return Response(
+            {"detail": f"Failed to get task status: {str(e)}"},
+            status=status.HTTP_500_INTERNAL_SERVER_ERROR,
+        )
+
+
+@api_view(["GET"])
+@permission_classes([IsAdmin])
+def get_download_token(request, filename):
+    """Get a signed token for downloading a backup file."""
+    try:
+        # Security: prevent path traversal
+        if ".." in filename or "/" in filename or "\\" in filename:
+            raise Http404("Invalid filename")
+
+        backup_dir = services.get_backup_dir()
+        backup_file = backup_dir / filename
+
+        if not backup_file.exists():
+            raise Http404("Backup file not found")
+
+        token = _generate_task_token(filename)
+        return Response({"token": token})
+    except Http404:
+        raise
+    except Exception as e:
+        return Response(
+            {"detail": f"Failed to generate token: {str(e)}"},
+            status=status.HTTP_500_INTERNAL_SERVER_ERROR,
+        )
+
+
+@api_view(["GET"])
+@permission_classes([AllowAny])
+def download_backup(request, filename):
+    """Download a backup file.
+
+    Requires either:
+    - Valid admin authentication, OR
+    - Valid download_token query parameter
+    """
+    # Check for token-based auth (avoids CORS preflight issues)
+    token = request.query_params.get("token")
+    if token:
+        if not _verify_task_token(filename, token):
+            return Response(
+                {"detail": "Invalid download token"},
+                status=status.HTTP_403_FORBIDDEN,
+            )
+    else:
+        # Fall back to admin auth check
+        if not request.user.is_authenticated or getattr(request.user, 'user_level', 0) < 10:
+            return Response(
+                {"detail": "Authentication required"},
+                status=status.HTTP_401_UNAUTHORIZED,
+            )
+
+    try:
+        # Security: prevent path traversal by checking for suspicious characters
+        if ".." in filename or "/" in filename or "\\" in filename:
+            raise Http404("Invalid filename")
+
+        backup_dir = services.get_backup_dir()
+        backup_file = (backup_dir / filename).resolve()
+
+        # Security: ensure the resolved path is still within backup_dir
+        if not str(backup_file).startswith(str(backup_dir.resolve())):
+            raise Http404("Invalid filename")
+
+        if not backup_file.exists() or not backup_file.is_file():
+            raise Http404("Backup file not found")
+
+        file_size = backup_file.stat().st_size
+
+        # Use X-Accel-Redirect for nginx (AIO container) - nginx serves file directly
+        # Fall back to streaming for non-nginx deployments
+        use_nginx_accel = os.environ.get("USE_NGINX_ACCEL", "").lower() == "true"
+        logger.info(f"[DOWNLOAD] File: {filename}, Size: {file_size}, USE_NGINX_ACCEL: {use_nginx_accel}")
+
+        if use_nginx_accel:
+            # X-Accel-Redirect: Django returns immediately, nginx serves file
+            logger.info(f"[DOWNLOAD] Using X-Accel-Redirect: /protected-backups/{filename}")
+            response = HttpResponse()
+            response["X-Accel-Redirect"] = f"/protected-backups/{filename}"
+            response["Content-Type"] = "application/zip"
+            response["Content-Length"] = file_size
+            response["Content-Disposition"] = f'attachment; filename="{filename}"'
+            return response
+        else:
+            # Streaming fallback for non-nginx deployments
+            logger.info(f"[DOWNLOAD] Using streaming fallback (no nginx)")
+            def file_iterator(file_path, chunk_size=2 * 1024 * 1024):
+                with open(file_path, "rb") as f:
+                    while chunk := f.read(chunk_size):
+                        yield chunk
+
+            response = StreamingHttpResponse(
+                file_iterator(backup_file),
+                content_type="application/zip",
+            )
+            response["Content-Length"] = file_size
+            response["Content-Disposition"] = f'attachment; filename="{filename}"'
+            return response
+    except Http404:
+        raise
+    except Exception as e:
+        return Response(
+            {"detail": f"Download failed: {str(e)}"},
+            status=status.HTTP_500_INTERNAL_SERVER_ERROR,
+        )
+
+
+@api_view(["DELETE"])
+@permission_classes([IsAdmin])
+def delete_backup(request, filename):
+    """Delete a backup file."""
+    try:
+        # Security: prevent path traversal
+        if ".." in filename or "/" in filename or "\\" in filename:
+            raise Http404("Invalid filename")
+
+        services.delete_backup(filename)
+        return Response(
+            {"detail": "Backup deleted successfully"},
+            status=status.HTTP_204_NO_CONTENT,
+        )
+    except FileNotFoundError:
+        raise Http404("Backup file not found")
+    except Exception as e:
+        return Response(
+            {"detail": f"Delete failed: {str(e)}"},
+            status=status.HTTP_500_INTERNAL_SERVER_ERROR,
+        )
+
+
+@api_view(["POST"])
+@permission_classes([IsAdmin])
+@parser_classes([MultiPartParser, FormParser])
+def upload_backup(request):
+    """Upload a backup file for restoration."""
+    uploaded = request.FILES.get("file")
+    if not uploaded:
+        return Response(
+            {"detail": "No file uploaded"},
+            status=status.HTTP_400_BAD_REQUEST,
+        )
+
+    try:
+        backup_dir = services.get_backup_dir()
+        # Sanitize filename: strip directory components to prevent path traversal
+        filename = Path(uploaded.name or "uploaded-backup.zip").name
+        if not filename:
+            filename = "uploaded-backup.zip"
+
+        try:
+            safe_upload_path(filename, str(backup_dir))
+        except ValueError:
+            return Response({"detail": "Invalid filename."}, status=status.HTTP_400_BAD_REQUEST)
+
+        # Ensure unique filename
+        backup_file = (backup_dir / filename).resolve()
+        counter = 1
+        while backup_file.exists():
+            name_parts = filename.rsplit(".", 1)
+            if len(name_parts) == 2:
+                backup_file = backup_dir / f"{name_parts[0]}-{counter}.{name_parts[1]}"
+            else:
+                backup_file = backup_dir / f"{filename}-{counter}"
+            counter += 1
+
+        # Save uploaded file
+        with backup_file.open("wb") as f:
+            for chunk in uploaded.chunks():
+                f.write(chunk)
+
+        return Response(
+            {
+                "detail": "Backup uploaded successfully",
+                "filename": backup_file.name,
+            },
+            status=status.HTTP_201_CREATED,
+        )
+    except Exception as e:
+        return Response(
+            {"detail": f"Upload failed: {str(e)}"},
+            status=status.HTTP_500_INTERNAL_SERVER_ERROR,
+        )
+
+
+@api_view(["POST"])
+@permission_classes([IsAdmin])
+def restore_backup(request, filename):
+    """Restore from a backup file (async via Celery). WARNING: This will flush the database!"""
+    try:
+        # Security: prevent path traversal
+        if ".." in filename or "/" in filename or "\\" in filename:
+            raise Http404("Invalid filename")
+
+        backup_dir = services.get_backup_dir()
+        backup_file = backup_dir / filename
+
+        if not backup_file.exists():
+            raise Http404("Backup file not found")
+
+        task = restore_backup_task.delay(filename)
+        return Response(
+            {
+                "detail": "Restore started",
+                "task_id": task.id,
+                "task_token": _generate_task_token(task.id),
+            },
+            status=status.HTTP_202_ACCEPTED,
+        )
+    except Http404:
+        raise
+    except Exception as e:
+        return Response(
+            {"detail": f"Failed to start restore: {str(e)}"},
+            status=status.HTTP_500_INTERNAL_SERVER_ERROR,
+        )
+
+
+@api_view(["GET"])
+@permission_classes([IsAdmin])
+def get_schedule(request):
+    """Get backup schedule settings."""
+    try:
+        settings = get_schedule_settings()
+        return Response(settings)
+    except Exception as e:
+        return Response(
+            {"detail": f"Failed to get schedule: {str(e)}"},
+            status=status.HTTP_500_INTERNAL_SERVER_ERROR,
+        )
+
+
+@api_view(["PUT"])
+@permission_classes([IsAdmin])
+def update_schedule(request):
+    """Update backup schedule settings."""
+    try:
+        settings = update_schedule_settings(request.data)
+        return Response(settings)
+    except ValueError as e:
+        return Response(
+            {"detail": str(e)},
+            status=status.HTTP_400_BAD_REQUEST,
+        )
+    except Exception as e:
+        return Response(
+            {"detail": f"Failed to update schedule: {str(e)}"},
+            status=status.HTTP_500_INTERNAL_SERVER_ERROR,
+        )

apps/backups/apps.py

@@ -0,0 +1,40 @@
+import logging
+
+from django.apps import AppConfig
+
+logger = logging.getLogger(__name__)
+
+
+class BackupsConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "apps.backups"
+    verbose_name = "Backups"
+
+    def ready(self):
+        """Initialize backup scheduler on app startup."""
+        from dispatcharr.app_initialization import should_skip_initialization
+
+        # Skip if this is a management command, worker process, or dev server
+        if should_skip_initialization():
+            return
+
+        logger.debug("Syncing backup scheduler on app startup")
+        self._sync_backup_scheduler()
+
+    def _sync_backup_scheduler(self):
+        """Sync backup scheduler task to database."""
+        from core.models import CoreSettings
+        from .scheduler import _sync_periodic_task, DEFAULTS
+        try:
+            # Ensure settings exist with defaults if this is a new install
+            CoreSettings.objects.get_or_create(
+                key="backup_settings",
+                defaults={"name": "Backup Settings", "value": DEFAULTS.copy()}
+            )
+
+            # Always sync the periodic task (handles new installs, updates, or missing tasks)
+            logger.debug("Syncing backup scheduler")
+            _sync_periodic_task()
+        except Exception as e:
+            # Log but don't fail startup if there's an issue
+            logger.warning(f"Failed to initialize backup scheduler: {e}")

apps/backups/scheduler.py

@@ -0,0 +1,133 @@
+import json
+import logging
+
+from django_celery_beat.models import PeriodicTask
+
+from core.models import CoreSettings
+from core.scheduling import (
+    create_or_update_periodic_task,
+    delete_periodic_task,
+)
+
+logger = logging.getLogger(__name__)
+
+BACKUP_SCHEDULE_TASK_NAME = "backup-scheduled-task"
+
+DEFAULTS = {
+    "schedule_enabled": True,
+    "schedule_frequency": "daily",
+    "schedule_time": "03:00",
+    "schedule_day_of_week": 0,  # Sunday
+    "retention_count": 3,
+    "schedule_cron_expression": "",
+}
+
+
+def _get_backup_settings():
+    """Get all backup settings from CoreSettings grouped JSON."""
+    try:
+        settings_obj = CoreSettings.objects.get(key="backup_settings")
+        return settings_obj.value if isinstance(settings_obj.value, dict) else DEFAULTS.copy()
+    except CoreSettings.DoesNotExist:
+        return DEFAULTS.copy()
+
+
+def _update_backup_settings(updates: dict) -> None:
+    """Update backup settings in the grouped JSON."""
+    obj, created = CoreSettings.objects.get_or_create(
+        key="backup_settings",
+        defaults={"name": "Backup Settings", "value": DEFAULTS.copy()}
+    )
+    current = obj.value if isinstance(obj.value, dict) else {}
+    current.update(updates)
+    obj.value = current
+    obj.save()
+
+
+def get_schedule_settings() -> dict:
+    """Get all backup schedule settings."""
+    settings = _get_backup_settings()
+    return {
+        "enabled": bool(settings.get("schedule_enabled", DEFAULTS["schedule_enabled"])),
+        "frequency": str(settings.get("schedule_frequency", DEFAULTS["schedule_frequency"])),
+        "time": str(settings.get("schedule_time", DEFAULTS["schedule_time"])),
+        "day_of_week": int(settings.get("schedule_day_of_week", DEFAULTS["schedule_day_of_week"])),
+        "retention_count": int(settings.get("retention_count", DEFAULTS["retention_count"])),
+        "cron_expression": str(settings.get("schedule_cron_expression", DEFAULTS["schedule_cron_expression"])),
+    }
+
+
+def update_schedule_settings(data: dict) -> dict:
+    """Update backup schedule settings and sync the PeriodicTask."""
+    # Validate
+    if "frequency" in data and data["frequency"] not in ("daily", "weekly"):
+        raise ValueError("frequency must be 'daily' or 'weekly'")
+
+    if "time" in data:
+        try:
+            hour, minute = data["time"].split(":")
+            int(hour)
+            int(minute)
+        except (ValueError, AttributeError):
+            raise ValueError("time must be in HH:MM format")
+
+    if "day_of_week" in data:
+        day = int(data["day_of_week"])
+        if day < 0 or day > 6:
+            raise ValueError("day_of_week must be 0-6 (Sunday-Saturday)")
+
+    if "retention_count" in data:
+        count = int(data["retention_count"])
+        if count < 0:
+            raise ValueError("retention_count must be >= 0")
+
+    # Update settings with proper key names
+    updates = {}
+    if "enabled" in data:
+        updates["schedule_enabled"] = bool(data["enabled"])
+    if "frequency" in data:
+        updates["schedule_frequency"] = str(data["frequency"])
+    if "time" in data:
+        updates["schedule_time"] = str(data["time"])
+    if "day_of_week" in data:
+        updates["schedule_day_of_week"] = int(data["day_of_week"])
+    if "retention_count" in data:
+        updates["retention_count"] = int(data["retention_count"])
+    if "cron_expression" in data:
+        updates["schedule_cron_expression"] = str(data["cron_expression"])
+
+    _update_backup_settings(updates)
+
+    # Sync the periodic task
+    _sync_periodic_task()
+
+    return get_schedule_settings()
+
+
+def _sync_periodic_task() -> None:
+    """Create, update, or delete the scheduled backup task based on settings."""
+    settings = get_schedule_settings()
+
+    if not settings["enabled"]:
+        delete_periodic_task(BACKUP_SCHEDULE_TASK_NAME)
+        logger.info("Backup schedule disabled, removed periodic task")
+        return
+
+    # Check if using cron expression (advanced mode)
+    if settings["cron_expression"]:
+        cron_expr = settings["cron_expression"]
+    else:
+        # Build a cron expression from simple frequency settings
+        hour, minute = settings["time"].split(":")
+        if settings["frequency"] == "daily":
+            cron_expr = f"{minute} {hour} * * *"
+        else:  # weekly
+            cron_expr = f"{minute} {hour} * * {settings['day_of_week']}"
+
+    create_or_update_periodic_task(
+        task_name=BACKUP_SCHEDULE_TASK_NAME,
+        celery_task_path="apps.backups.tasks.scheduled_backup_task",
+        kwargs={"retention_count": settings["retention_count"]},
+        cron_expression=cron_expr,
+        enabled=True,
+    )

apps/backups/services.py

@@ -0,0 +1,376 @@
+import datetime
+import json
+import os
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+from zipfile import ZipFile, ZIP_DEFLATED
+import logging
+import pytz
+
+from django.conf import settings
+from core.models import CoreSettings
+
+logger = logging.getLogger(__name__)
+
+
+def get_backup_dir() -> Path:
+    """Get the backup directory, creating it if necessary."""
+    backup_dir = Path(settings.BACKUP_ROOT)
+    backup_dir.mkdir(parents=True, exist_ok=True)
+    return backup_dir
+
+
+def _is_postgresql() -> bool:
+    """Check if we're using PostgreSQL."""
+    return settings.DATABASES["default"]["ENGINE"] == "django.db.backends.postgresql"
+
+
+def _get_pg_env() -> dict:
+    """Get environment variables for PostgreSQL commands.
+
+    Includes PGPASSWORD for password auth and PGSSL* variables for TLS.
+    Reads TLS config from DATABASES['default']['OPTIONS'], which is
+    populated by settings.py when POSTGRES_SSL=true.
+    """
+    db_config = settings.DATABASES["default"]
+    env = os.environ.copy()
+
+    password = db_config.get("PASSWORD", "")
+    if password:
+        env["PGPASSWORD"] = password
+    else:
+        env.pop("PGPASSWORD", None)
+
+    # Propagate TLS configuration from Django OPTIONS to libpq env vars.
+    options = db_config.get("OPTIONS", {})
+    _ssl_env_map = {
+        "sslmode": "PGSSLMODE",
+        "sslrootcert": "PGSSLROOTCERT",
+        "sslcert": "PGSSLCERT",
+        "sslkey": "PGSSLKEY",
+    }
+    # Always strip inherited PGSSL* vars first, then set only what is explicitly configured
+    for opt_key, env_key in _ssl_env_map.items():
+        env.pop(env_key, None)
+        value = options.get(opt_key)
+        if value:
+            env[env_key] = value
+
+    return env
+
+
+def _get_pg_args() -> list[str]:
+    """Get common PostgreSQL command arguments."""
+    db_config = settings.DATABASES["default"]
+    return [
+        "-h", db_config.get("HOST", "localhost"),
+        "-p", str(db_config.get("PORT", 5432)),
+        "-U", db_config.get("USER", "postgres"),
+        "-d", db_config.get("NAME", "dispatcharr"),
+    ]
+
+
+def _dump_postgresql(output_file: Path) -> None:
+    """Dump PostgreSQL database using pg_dump."""
+    logger.info("Dumping PostgreSQL database with pg_dump...")
+
+    cmd = [
+        "pg_dump",
+        *_get_pg_args(),
+        "-Fc",  # Custom format for pg_restore
+        "-v",   # Verbose
+        "-f", str(output_file),
+    ]
+
+    result = subprocess.run(
+        cmd,
+        env=_get_pg_env(),
+        capture_output=True,
+        text=True,
+    )
+
+    if result.returncode != 0:
+        logger.error(f"pg_dump failed: {result.stderr}")
+        raise RuntimeError(f"pg_dump failed: {result.stderr}")
+
+    logger.debug(f"pg_dump output: {result.stderr}")
+
+
+def _clean_postgresql_schema() -> None:
+    """Drop and recreate the public schema to ensure a completely clean restore."""
+    logger.info("[PG_CLEAN] Dropping and recreating public schema...")
+
+    # Commands to drop and recreate schema
+    sql_commands = "DROP SCHEMA IF EXISTS public CASCADE; CREATE SCHEMA public; GRANT ALL ON SCHEMA public TO public;"
+
+    cmd = [
+        "psql",
+        *_get_pg_args(),
+        "-c", sql_commands,
+    ]
+
+    result = subprocess.run(
+        cmd,
+        env=_get_pg_env(),
+        capture_output=True,
+        text=True,
+    )
+
+    if result.returncode != 0:
+        logger.error(f"[PG_CLEAN] Failed to clean schema: {result.stderr}")
+        raise RuntimeError(f"Failed to clean PostgreSQL schema: {result.stderr}")
+
+    logger.info("[PG_CLEAN] Schema cleaned successfully")
+
+
+def _restore_postgresql(dump_file: Path) -> None:
+    """Restore PostgreSQL database using pg_restore."""
+    logger.info("[PG_RESTORE] Starting pg_restore...")
+    logger.info(f"[PG_RESTORE] Dump file: {dump_file}")
+
+    # Drop and recreate schema to ensure a completely clean restore
+    _clean_postgresql_schema()
+
+    pg_args = _get_pg_args()
+    logger.info(f"[PG_RESTORE] Connection args: {pg_args}")
+
+    cmd = [
+        "pg_restore",
+        "--no-owner",  # Skip ownership commands (we already created schema)
+        *pg_args,
+        "-v",  # Verbose
+        str(dump_file),
+    ]
+
+    logger.info(f"[PG_RESTORE] Running command: {' '.join(cmd)}")
+
+    result = subprocess.run(
+        cmd,
+        env=_get_pg_env(),
+        capture_output=True,
+        text=True,
+    )
+
+    logger.info(f"[PG_RESTORE] Return code: {result.returncode}")
+
+    # pg_restore may return non-zero even on partial success
+    # Check for actual errors vs warnings
+    if result.returncode != 0:
+        # Some errors during restore are expected (e.g., "does not exist" when cleaning)
+        # Only fail on critical errors
+        stderr = result.stderr.lower()
+        if "fatal" in stderr or "could not connect" in stderr:
+            logger.error(f"[PG_RESTORE] Failed critically: {result.stderr}")
+            raise RuntimeError(f"pg_restore failed: {result.stderr}")
+        else:
+            logger.warning(f"[PG_RESTORE] Completed with warnings: {result.stderr[:500]}...")
+
+    logger.info("[PG_RESTORE] Completed successfully")
+
+
+def _dump_sqlite(output_file: Path) -> None:
+    """Dump SQLite database using sqlite3 .backup command."""
+    logger.info("Dumping SQLite database with sqlite3 .backup...")
+    db_path = Path(settings.DATABASES["default"]["NAME"])
+
+    if not db_path.exists():
+        raise FileNotFoundError(f"SQLite database not found: {db_path}")
+
+    # Use sqlite3 .backup command via stdin for reliable execution
+    result = subprocess.run(
+        ["sqlite3", str(db_path)],
+        input=f".backup '{output_file}'\n",
+        capture_output=True,
+        text=True,
+    )
+
+    if result.returncode != 0:
+        logger.error(f"sqlite3 backup failed: {result.stderr}")
+        raise RuntimeError(f"sqlite3 backup failed: {result.stderr}")
+
+    # Verify the backup file was created
+    if not output_file.exists():
+        raise RuntimeError("sqlite3 backup failed: output file not created")
+
+    logger.info(f"sqlite3 backup completed successfully: {output_file}")
+
+
+def _restore_sqlite(dump_file: Path) -> None:
+    """Restore SQLite database by replacing the database file."""
+    logger.info("Restoring SQLite database...")
+    db_path = Path(settings.DATABASES["default"]["NAME"])
+    backup_current = None
+
+    # Backup current database before overwriting
+    if db_path.exists():
+        backup_current = db_path.with_suffix(".db.bak")
+        shutil.copy2(db_path, backup_current)
+        logger.info(f"Backed up current database to {backup_current}")
+
+    # Ensure parent directory exists
+    db_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # The backup file from _dump_sqlite is a complete SQLite database file
+    # We can simply copy it over the existing database
+    shutil.copy2(dump_file, db_path)
+
+    # Verify the restore worked by checking if sqlite3 can read it
+    result = subprocess.run(
+        ["sqlite3", str(db_path)],
+        input=".tables\n",
+        capture_output=True,
+        text=True,
+    )
+
+    if result.returncode != 0:
+        logger.error(f"sqlite3 verification failed: {result.stderr}")
+        # Try to restore from backup
+        if backup_current and backup_current.exists():
+            shutil.copy2(backup_current, db_path)
+            logger.info("Restored original database from backup")
+        raise RuntimeError(f"sqlite3 restore verification failed: {result.stderr}")
+
+    logger.info("sqlite3 restore completed successfully")
+
+
+def create_backup() -> Path:
+    """
+    Create a backup archive containing database dump and data directories.
+    Returns the path to the created backup file.
+    """
+    backup_dir = get_backup_dir()
+
+    # Use system timezone for filename (user-friendly), but keep internal timestamps as UTC
+    system_tz_name = CoreSettings.get_system_time_zone()
+    try:
+        system_tz = pytz.timezone(system_tz_name)
+        now_local = datetime.datetime.now(datetime.UTC).astimezone(system_tz)
+        timestamp = now_local.strftime("%Y.%m.%d.%H.%M.%S")
+    except Exception as e:
+        logger.warning(f"Failed to use system timezone {system_tz_name}: {e}, falling back to UTC")
+        timestamp = datetime.datetime.now(datetime.UTC).strftime("%Y.%m.%d.%H.%M.%S")
+
+    backup_name = f"dispatcharr-backup-{timestamp}.zip"
+    backup_file = backup_dir / backup_name
+
+    logger.info(f"Creating backup: {backup_name}")
+
+    with tempfile.TemporaryDirectory(prefix="dispatcharr-backup-") as temp_dir:
+        temp_path = Path(temp_dir)
+
+        # Determine database type and dump accordingly
+        if _is_postgresql():
+            db_dump_file = temp_path / "database.dump"
+            _dump_postgresql(db_dump_file)
+            db_type = "postgresql"
+        else:
+            db_dump_file = temp_path / "database.sqlite3"
+            _dump_sqlite(db_dump_file)
+            db_type = "sqlite"
+
+        # Create ZIP archive with compression and ZIP64 support for large files
+        with ZipFile(backup_file, "w", compression=ZIP_DEFLATED, allowZip64=True) as zip_file:
+            # Add database dump
+            zip_file.write(db_dump_file, db_dump_file.name)
+
+            # Add metadata
+            metadata = {
+                "format": "dispatcharr-backup",
+                "version": 2,
+                "database_type": db_type,
+                "database_file": db_dump_file.name,
+                "created_at": datetime.datetime.now(datetime.UTC).isoformat(),
+            }
+            zip_file.writestr("metadata.json", json.dumps(metadata, indent=2))
+
+    logger.info(f"Backup created successfully: {backup_file}")
+    return backup_file
+
+
+def restore_backup(backup_file: Path) -> None:
+    """
+    Restore from a backup archive.
+    WARNING: This will overwrite the database!
+    """
+    if not backup_file.exists():
+        raise FileNotFoundError(f"Backup file not found: {backup_file}")
+
+    logger.info(f"Restoring from backup: {backup_file}")
+
+    with tempfile.TemporaryDirectory(prefix="dispatcharr-restore-") as temp_dir:
+        temp_path = Path(temp_dir)
+
+        # Extract backup
+        logger.debug("Extracting backup archive...")
+        with ZipFile(backup_file, "r") as zip_file:
+            zip_file.extractall(temp_path)
+
+        # Read metadata
+        metadata_file = temp_path / "metadata.json"
+        if not metadata_file.exists():
+            raise ValueError("Invalid backup: missing metadata.json")
+
+        with open(metadata_file) as f:
+            metadata = json.load(f)
+
+        # Restore database
+        _restore_database(temp_path, metadata)
+
+    logger.info("Restore completed successfully")
+
+
+def _restore_database(temp_path: Path, metadata: dict) -> None:
+    """Restore database from backup."""
+    db_type = metadata.get("database_type", "postgresql")
+    db_file = metadata.get("database_file", "database.dump")
+    dump_file = temp_path / db_file
+
+    if not dump_file.exists():
+        raise ValueError(f"Invalid backup: missing {db_file}")
+
+    current_db_type = "postgresql" if _is_postgresql() else "sqlite"
+
+    if db_type != current_db_type:
+        raise ValueError(
+            f"Database type mismatch: backup is {db_type}, "
+            f"but current database is {current_db_type}"
+        )
+
+    if db_type == "postgresql":
+        _restore_postgresql(dump_file)
+    else:
+        _restore_sqlite(dump_file)
+
+
+def list_backups() -> list[dict]:
+    """List all available backup files with metadata."""
+    backup_dir = get_backup_dir()
+    backups = []
+
+    for backup_file in sorted(backup_dir.glob("dispatcharr-backup-*.zip"), reverse=True):
+        # Use UTC timezone so frontend can convert to user's local time
+        created_time = datetime.datetime.fromtimestamp(backup_file.stat().st_mtime, datetime.UTC)
+        backups.append({
+            "name": backup_file.name,
+            "size": backup_file.stat().st_size,
+            "created": created_time.isoformat(),
+        })
+
+    return backups
+
+
+def delete_backup(filename: str) -> None:
+    """Delete a backup file."""
+    backup_dir = get_backup_dir()
+    backup_file = backup_dir / filename
+
+    if not backup_file.exists():
+        raise FileNotFoundError(f"Backup file not found: {filename}")
+
+    if not backup_file.is_file():
+        raise ValueError(f"Invalid backup file: {filename}")
+
+    backup_file.unlink()
+    logger.info(f"Deleted backup: {filename}")

apps/backups/tasks.py

@@ -0,0 +1,106 @@
+import logging
+import traceback
+from celery import shared_task
+
+from . import services
+
+logger = logging.getLogger(__name__)
+
+
+def _cleanup_old_backups(retention_count: int) -> int:
+    """Delete old backups, keeping only the most recent N. Returns count deleted."""
+    if retention_count <= 0:
+        return 0
+
+    backups = services.list_backups()
+    if len(backups) <= retention_count:
+        return 0
+
+    # Backups are sorted newest first, so delete from the end
+    to_delete = backups[retention_count:]
+    deleted = 0
+
+    for backup in to_delete:
+        try:
+            services.delete_backup(backup["name"])
+            deleted += 1
+            logger.info(f"[CLEANUP] Deleted old backup: {backup['name']}")
+        except Exception as e:
+            logger.error(f"[CLEANUP] Failed to delete {backup['name']}: {e}")
+
+    return deleted
+
+
+@shared_task(bind=True)
+def create_backup_task(self):
+    """Celery task to create a backup asynchronously."""
+    try:
+        logger.info(f"[BACKUP] Starting backup task {self.request.id}")
+        backup_file = services.create_backup()
+        logger.info(f"[BACKUP] Task {self.request.id} completed: {backup_file.name}")
+        return {
+            "status": "completed",
+            "filename": backup_file.name,
+            "size": backup_file.stat().st_size,
+        }
+    except Exception as e:
+        logger.error(f"[BACKUP] Task {self.request.id} failed: {str(e)}")
+        logger.error(f"[BACKUP] Traceback: {traceback.format_exc()}")
+        return {
+            "status": "failed",
+            "error": str(e),
+        }
+
+
+@shared_task(bind=True)
+def restore_backup_task(self, filename: str):
+    """Celery task to restore a backup asynchronously."""
+    try:
+        logger.info(f"[RESTORE] Starting restore task {self.request.id} for {filename}")
+        backup_dir = services.get_backup_dir()
+        backup_file = backup_dir / filename
+        logger.info(f"[RESTORE] Backup file path: {backup_file}")
+        services.restore_backup(backup_file)
+        logger.info(f"[RESTORE] Task {self.request.id} completed successfully")
+        return {
+            "status": "completed",
+            "filename": filename,
+        }
+    except Exception as e:
+        logger.error(f"[RESTORE] Task {self.request.id} failed: {str(e)}")
+        logger.error(f"[RESTORE] Traceback: {traceback.format_exc()}")
+        return {
+            "status": "failed",
+            "error": str(e),
+        }
+
+
+@shared_task(bind=True)
+def scheduled_backup_task(self, retention_count: int = 0):
+    """Celery task for scheduled backups with optional retention cleanup."""
+    try:
+        logger.info(f"[SCHEDULED] Starting scheduled backup task {self.request.id}")
+
+        # Create backup
+        backup_file = services.create_backup()
+        logger.info(f"[SCHEDULED] Backup created: {backup_file.name}")
+
+        # Cleanup old backups if retention is set
+        deleted = 0
+        if retention_count > 0:
+            deleted = _cleanup_old_backups(retention_count)
+            logger.info(f"[SCHEDULED] Cleanup complete, deleted {deleted} old backup(s)")
+
+        return {
+            "status": "completed",
+            "filename": backup_file.name,
+            "size": backup_file.stat().st_size,
+            "deleted_count": deleted,
+        }
+    except Exception as e:
+        logger.error(f"[SCHEDULED] Task {self.request.id} failed: {str(e)}")
+        logger.error(f"[SCHEDULED] Traceback: {traceback.format_exc()}")
+        return {
+            "status": "failed",
+            "error": str(e),
+        }

apps/channels/admin.py

@@ -0,0 +1,38 @@
+from django.contrib import admin
+from .models import Stream, Channel, ChannelGroup
+
+@admin.register(Stream)
+class StreamAdmin(admin.ModelAdmin):
+    list_display = (
+        'id',  # Primary Key
+        'name',
+        'channel_group',
+        'url',
+        'current_viewers',
+        'updated_at',
+    )
+
+    list_filter = ('channel_group',)  # Filter by 'channel_group' (foreign key)
+
+    search_fields = ('id', 'name', 'url', 'channel_group__name')  # Search by 'ChannelGroup' name
+
+    ordering = ('-updated_at',)
+
+@admin.register(Channel)
+class ChannelAdmin(admin.ModelAdmin):
+    list_display = (
+        'id',  # Primary Key
+        'channel_number',
+        'uuid',
+        'name',
+        'channel_group',
+        'epg_data'
+    )
+    list_filter = ('channel_group',)
+    search_fields = ('id', 'name', 'channel_group__name', 'epg_data')  # Added 'id'
+    ordering = ('channel_number',)
+
+@admin.register(ChannelGroup)
+class ChannelGroupAdmin(admin.ModelAdmin):
+    list_display = ('id', 'name')  # Added 'id'
+    search_fields = ('id', 'name')  # Added 'id'

apps/channels/api_urls.py

@@ -0,0 +1,55 @@
+from django.urls import path, include
+from rest_framework.routers import DefaultRouter
+from .api_views import (
+    StreamViewSet,
+    ChannelViewSet,
+    ChannelGroupViewSet,
+    BulkDeleteStreamsAPIView,
+    BulkDeleteChannelsAPIView,
+    BulkDeleteLogosAPIView,
+    CleanupUnusedLogosAPIView,
+    LogoViewSet,
+    ChannelProfileViewSet,
+    UpdateChannelMembershipAPIView,
+    BulkUpdateChannelMembershipAPIView,
+    RecordingViewSet,
+    RecurringRecordingRuleViewSet,
+    GetChannelStreamsAPIView,
+    SeriesRulesAPIView,
+    DeleteSeriesRuleAPIView,
+    EvaluateSeriesRulesAPIView,
+    BulkRemoveSeriesRecordingsAPIView,
+    BulkDeleteUpcomingRecordingsAPIView,
+    ComskipConfigAPIView,
+)
+
+app_name = 'channels'  # for DRF routing
+
+router = DefaultRouter()
+router.register(r'streams', StreamViewSet, basename='stream')
+router.register(r'groups', ChannelGroupViewSet, basename='channel-group')
+router.register(r'channels', ChannelViewSet, basename='channel')
+router.register(r'logos', LogoViewSet, basename='logo')
+router.register(r'profiles', ChannelProfileViewSet, basename='profile')
+router.register(r'recordings', RecordingViewSet, basename='recording')
+router.register(r'recurring-rules', RecurringRecordingRuleViewSet, basename='recurring-rule')
+
+urlpatterns = [
+    # Bulk delete is a single APIView, not a ViewSet
+    path('streams/bulk-delete/', BulkDeleteStreamsAPIView.as_view(), name='bulk_delete_streams'),
+    path('channels/bulk-delete/', BulkDeleteChannelsAPIView.as_view(), name='bulk_delete_channels'),
+    path('logos/bulk-delete/', BulkDeleteLogosAPIView.as_view(), name='bulk_delete_logos'),
+    path('logos/cleanup/', CleanupUnusedLogosAPIView.as_view(), name='cleanup_unused_logos'),
+    path('channels/<int:channel_id>/streams/', GetChannelStreamsAPIView.as_view(), name='get_channel_streams'),
+    path('profiles/<int:profile_id>/channels/<int:channel_id>/', UpdateChannelMembershipAPIView.as_view(), name='update_channel_membership'),
+    path('profiles/<int:profile_id>/channels/bulk-update/', BulkUpdateChannelMembershipAPIView.as_view(), name='bulk_update_channel_membership'),
+    # DVR series rules (order matters: specific routes before catch-all slug)
+    path('series-rules/', SeriesRulesAPIView.as_view(), name='series_rules'),
+    path('series-rules/evaluate/', EvaluateSeriesRulesAPIView.as_view(), name='evaluate_series_rules'),
+    path('series-rules/bulk-remove/', BulkRemoveSeriesRecordingsAPIView.as_view(), name='bulk_remove_series_recordings'),
+    path('series-rules/<path:tvg_id>/', DeleteSeriesRuleAPIView.as_view(), name='delete_series_rule'),
+    path('recordings/bulk-delete-upcoming/', BulkDeleteUpcomingRecordingsAPIView.as_view(), name='bulk_delete_upcoming_recordings'),
+    path('dvr/comskip-config/', ComskipConfigAPIView.as_view(), name='comskip_config'),
+]
+
+urlpatterns += router.urls

apps/channels/apps.py

@@ -0,0 +1,11 @@
+from django.apps import AppConfig
+
+class ChannelsConfig(AppConfig):
+    default_auto_field = 'django.db.models.BigAutoField'
+    name = 'apps.channels'
+    verbose_name = "Channel & Stream Management"
+    label = 'dispatcharr_channels'
+
+    def ready(self):
+        # Import signals so they get registered.
+        import apps.channels.signals

apps/channels/forms.py

@@ -0,0 +1,53 @@
+from django import forms
+from .models import Stream, Channel, ChannelGroup
+
+#
+# ChannelGroup Form
+#
+class ChannelGroupForm(forms.ModelForm):
+    class Meta:
+        model = ChannelGroup
+        fields = ['name']
+
+
+#
+# Channel Form
+#
+class ChannelForm(forms.ModelForm):
+    # Explicitly define channel_number as FloatField to ensure decimal values work
+    channel_number = forms.FloatField(
+        required=False,
+        widget=forms.NumberInput(attrs={'step': '0.1'}),  # Allow decimal steps
+        help_text="Channel number can include decimals (e.g., 1.1, 2.5)"
+    )
+
+    channel_group = forms.ModelChoiceField(
+        queryset=ChannelGroup.objects.all(),
+        required=False,
+        label="Channel Group",
+        empty_label="--- No group ---"
+    )
+
+    class Meta:
+        model = Channel
+        fields = [
+            'channel_number',
+            'name',
+            'channel_group',
+        ]
+
+
+#
+# Example: Stream Form (optional if you want a ModelForm for Streams)
+#
+class StreamForm(forms.ModelForm):
+    class Meta:
+        model = Stream
+        fields = [
+            'name',
+            'url',
+            'logo_url',
+            'epg_data',
+            'local_file',
+            'channel_group',
+        ]

apps/channels/migrations/0001_initial.py

@@ -0,0 +1,77 @@
+# Generated by Django 5.1.6 on 2025-03-05 22:07
+
+import django.db.models.deletion
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = [
+        ('core', '0001_initial'),
+        ('m3u', '0001_initial'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='ChannelGroup',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('name', models.CharField(max_length=100, unique=True)),
+            ],
+        ),
+        migrations.CreateModel(
+            name='Channel',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('channel_number', models.IntegerField()),
+                ('channel_name', models.CharField(max_length=255)),
+                ('logo_url', models.URLField(blank=True, max_length=2000, null=True)),
+                ('logo_file', models.ImageField(blank=True, null=True, upload_to='logos/')),
+                ('tvg_id', models.CharField(blank=True, max_length=255, null=True)),
+                ('tvg_name', models.CharField(blank=True, max_length=255, null=True)),
+                ('stream_profile', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='channels', to='core.streamprofile')),
+                ('channel_group', models.ForeignKey(blank=True, help_text='Channel group this channel belongs to.', null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='channels', to='dispatcharr_channels.channelgroup')),
+            ],
+        ),
+        migrations.CreateModel(
+            name='Stream',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('name', models.CharField(default='Default Stream', max_length=255)),
+                ('url', models.URLField()),
+                ('custom_url', models.URLField(blank=True, max_length=2000, null=True)),
+                ('logo_url', models.URLField(blank=True, max_length=2000, null=True)),
+                ('tvg_id', models.CharField(blank=True, max_length=255, null=True)),
+                ('local_file', models.FileField(blank=True, null=True, upload_to='uploads/')),
+                ('current_viewers', models.PositiveIntegerField(default=0)),
+                ('updated_at', models.DateTimeField(auto_now=True)),
+                ('group_name', models.CharField(blank=True, max_length=255, null=True)),
+                ('m3u_account', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.CASCADE, related_name='streams', to='m3u.m3uaccount')),
+                ('stream_profile', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='streams', to='core.streamprofile')),
+            ],
+            options={
+                'verbose_name': 'Stream',
+                'verbose_name_plural': 'Streams',
+                'ordering': ['-updated_at'],
+            },
+        ),
+        migrations.CreateModel(
+            name='ChannelStream',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('order', models.PositiveIntegerField(default=0)),
+                ('channel', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, to='dispatcharr_channels.channel')),
+                ('stream', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, to='dispatcharr_channels.stream')),
+            ],
+            options={
+                'ordering': ['order'],
+            },
+        ),
+        migrations.AddField(
+            model_name='channel',
+            name='streams',
+            field=models.ManyToManyField(blank=True, related_name='channels', through='dispatcharr_channels.ChannelStream', to='dispatcharr_channels.stream'),
+        ),
+    ]

apps/channels/migrations/0002_rename_channel_name_channel_name_and_more.py

@@ -0,0 +1,27 @@
+# Generated by Django 5.1.6 on 2025-03-16 12:21
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('dispatcharr_channels', '0001_initial'),
+    ]
+
+    operations = [
+        migrations.RenameField(
+            model_name='channel',
+            old_name='channel_name',
+            new_name='name',
+        ),
+        migrations.RemoveField(
+            model_name='stream',
+            name='url',
+        ),
+        migrations.RenameField(
+            model_name='stream',
+            old_name='custom_url',
+            new_name='url',
+        ),
+    ]

apps/channels/migrations/0003_channel_uuid.py

@@ -0,0 +1,38 @@
+# Generated by Django 5.1.6 on 2025-03-16 13:25
+
+import uuid
+from django.db import migrations, models
+
+
+# Generated by Django 5.1.6 on 2025-03-16 13:25
+
+import uuid
+from django.db import migrations, models
+
+
+def generate_uuids(apps, schema_editor):
+    Channel = apps.get_model('dispatcharr_channels', 'Channel')
+    for channel in Channel.objects.all():
+        if not channel.uuid:
+            channel.uuid = uuid.uuid4()
+            channel.save()
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('dispatcharr_channels', '0002_rename_channel_name_channel_name_and_more'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='channel',
+            name='uuid',
+            field=models.UUIDField(default=uuid.uuid4, editable=False),
+        ),
+        migrations.RunPython(generate_uuids),
+        migrations.AlterField(
+            model_name='channel',
+            name='uuid',
+            field=models.UUIDField(default=uuid.uuid4, editable=False, unique=True),
+        ),
+    ]

apps/channels/migrations/0004_stream_is_custom.py

@@ -0,0 +1,18 @@
+# Generated by Django 5.1.6 on 2025-03-17 21:16
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('dispatcharr_channels', '0003_channel_uuid'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='stream',
+            name='is_custom',
+            field=models.BooleanField(default=False, help_text='Whether this is a user-created stream or from an M3U account'),
+        ),
+    ]

apps/channels/migrations/0005_stream_channel_group_stream_last_seen_and_more.py

@@ -0,0 +1,44 @@
+# Generated by Django 5.1.6 on 2025-03-19 16:33
+
+import django.db.models.deletion
+import django.utils.timezone
+import uuid
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('dispatcharr_channels', '0004_stream_is_custom'),
+        ('m3u', '0003_create_custom_account'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='stream',
+            name='channel_group',
+            field=models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='streams', to='dispatcharr_channels.channelgroup'),
+        ),
+        migrations.AddField(
+            model_name='stream',
+            name='last_seen',
+            field=models.DateTimeField(db_index=True, default=django.utils.timezone.now),
+        ),
+        migrations.AlterField(
+            model_name='channel',
+            name='uuid',
+            field=models.UUIDField(db_index=True, default=uuid.uuid4, editable=False, unique=True),
+        ),
+        migrations.CreateModel(
+            name='ChannelGroupM3UAccount',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('enabled', models.BooleanField(default=True)),
+                ('channel_group', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='m3u_account', to='dispatcharr_channels.channelgroup')),
+                ('m3u_account', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='channel_group', to='m3u.m3uaccount')),
+            ],
+            options={
+                'unique_together': {('channel_group', 'm3u_account')},
+            },
+        ),
+    ]

apps/channels/migrations/0006_migrate_stream_groups.py

@@ -0,0 +1,51 @@
+# In your app's migrations folder, create a new migration file
+# e.g., migrations/000X_migrate_channel_group_to_foreign_key.py
+
+from django.db import migrations
+
+def migrate_channel_group(apps, schema_editor):
+    Stream = apps.get_model('dispatcharr_channels', 'Stream')
+    ChannelGroup = apps.get_model('dispatcharr_channels', 'ChannelGroup')
+    ChannelGroupM3UAccount = apps.get_model('dispatcharr_channels', 'ChannelGroup')
+    M3UAccount = apps.get_model('m3u', 'M3UAccount')
+
+    streams_to_update = []
+    for stream in Stream.objects.all():
+        # If the stream has a 'channel_group' string, try to find or create the ChannelGroup
+        if stream.group_name:  # group_name holds the channel group string
+            channel_group_name = stream.group_name.strip()
+
+            # Try to find the ChannelGroup by name
+            channel_group, created = ChannelGroup.objects.get_or_create(name=channel_group_name)
+
+            # Set the foreign key to the found or newly created ChannelGroup
+            stream.channel_group = channel_group
+
+            streams_to_update.append(stream)
+
+            # If the stream has an M3U account, ensure the M3U account is linked
+            if stream.m3u_account:
+                ChannelGroupM3UAccount.objects.get_or_create(
+                    channel_group=channel_group,
+                    m3u_account=stream.m3u_account,
+                    enabled=True  # Or set it to whatever the default logic is
+                )
+
+    Stream.objects.bulk_update(streams_to_update, ['channel_group'])
+
+def reverse_migration(apps, schema_editor):
+    # This reverse migration would undo the changes, setting `channel_group` to `None` and clearing any relationships.
+    Stream = apps.get_model('yourapp', 'Stream')
+    for stream in Stream.objects.all():
+        stream.channel_group = None
+        stream.save()
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('dispatcharr_channels', '0005_stream_channel_group_stream_last_seen_and_more'),
+    ]
+
+    operations = [
+        migrations.RunPython(migrate_channel_group, reverse_code=reverse_migration),
+    ]

apps/channels/migrations/0007_remove_stream_group_name.py

@@ -0,0 +1,17 @@
+# Generated by Django 5.1.6 on 2025-03-19 16:43
+
+from django.db import migrations
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('dispatcharr_channels', '0006_migrate_stream_groups'),
+    ]
+
+    operations = [
+        migrations.RemoveField(
+            model_name='stream',
+            name='group_name',
+        ),
+    ]

apps/channels/migrations/0008_stream_stream_hash.py

@@ -0,0 +1,23 @@
+# Generated by Django 5.1.6 on 2025-03-19 18:21
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('dispatcharr_channels', '0007_remove_stream_group_name'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='stream',
+            name='stream_hash',
+            field=models.CharField(db_index=True, help_text='Unique hash for this stream from the M3U account', max_length=255, null=True, unique=True),
+        ),
+        migrations.AlterField(
+            model_name='stream',
+            name='logo_url',
+            field=models.TextField(blank=True, null=True),
+        ),
+    ]

apps/channels/migrations/0009_remove_channel_tvg_name_channel_epg_data.py

@@ -0,0 +1,24 @@
+# Generated by Django 5.1.6 on 2025-03-26 12:59
+
+import django.db.models.deletion
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('dispatcharr_channels', '0008_stream_stream_hash'),
+        ('epg', '0004_epgdata_epg_source_alter_epgdata_tvg_id'),
+    ]
+
+    operations = [
+        migrations.RemoveField(
+            model_name='channel',
+            name='tvg_name',
+        ),
+        migrations.AddField(
+            model_name='channel',
+            name='epg_data',
+            field=models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='channels', to='epg.epgdata'),
+        ),
+    ]

apps/channels/migrations/0010_stream_custom_properties.py

@@ -0,0 +1,18 @@
+# Generated by Django 5.1.6 on 2025-04-01 17:36
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('dispatcharr_channels', '0009_remove_channel_tvg_name_channel_epg_data'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='stream',
+            name='custom_properties',
+            field=models.TextField(blank=True, null=True),
+        ),
+    ]

apps/channels/migrations/0011_logo_remove_channel_logo_file_and_more.py

@@ -0,0 +1,35 @@
+# Generated by Django 5.1.6 on 2025-04-01 22:14
+
+import django.db.models.deletion
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('dispatcharr_channels', '0010_stream_custom_properties'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='Logo',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('name', models.CharField(max_length=255)),
+                ('url', models.URLField(unique=True)),
+            ],
+        ),
+        migrations.RemoveField(
+            model_name='channel',
+            name='logo_file',
+        ),
+        migrations.RemoveField(
+            model_name='channel',
+            name='logo_url',
+        ),
+        migrations.AddField(
+            model_name='channel',
+            name='logo',
+            field=models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='channels', to='dispatcharr_channels.logo'),
+        ),
+    ]

apps/channels/migrations/0012_channelprofile_channelprofilemembership.py

@@ -0,0 +1,33 @@
+# Generated by Django 5.1.6 on 2025-04-02 23:27
+
+import django.db.models.deletion
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('dispatcharr_channels', '0011_logo_remove_channel_logo_file_and_more'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='ChannelProfile',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('name', models.CharField(max_length=100, unique=True)),
+            ],
+        ),
+        migrations.CreateModel(
+            name='ChannelProfileMembership',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('enabled', models.BooleanField(default=True)),
+                ('channel', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, to='dispatcharr_channels.channel')),
+                ('channel_profile', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, to='dispatcharr_channels.channelprofile')),
+            ],
+            options={
+                'unique_together': {('channel_profile', 'channel')},
+            },
+        ),
+    ]

apps/channels/migrations/0013_alter_logo_url.py

@@ -0,0 +1,18 @@
+# Generated by Django 5.1.6 on 2025-04-04 15:04
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('dispatcharr_channels', '0012_channelprofile_channelprofilemembership'),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name='logo',
+            name='url',
+            field=models.TextField(unique=True),
+        ),
+    ]

apps/channels/migrations/0014_recording.py

@@ -0,0 +1,24 @@
+# Generated by Django 5.1.6 on 2025-04-05 22:25
+
+import django.db.models.deletion
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('dispatcharr_channels', '0013_alter_logo_url'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='Recording',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('start_time', models.DateTimeField()),
+                ('end_time', models.DateTimeField()),
+                ('task_id', models.CharField(blank=True, max_length=255, null=True)),
+                ('channel', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='recordings', to='dispatcharr_channels.channel')),
+            ],
+        ),
+    ]

apps/channels/migrations/0015_recording_custom_properties.py

@@ -0,0 +1,18 @@
+# Generated by Django 5.1.6 on 2025-04-07 16:47
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('dispatcharr_channels', '0014_recording'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='recording',
+            name='custom_properties',
+            field=models.TextField(blank=True, null=True),
+        ),
+    ]

apps/channels/migrations/0016_channelstream_unique_channel_stream.py

@@ -0,0 +1,38 @@
+# Generated by Django 5.1.6 on 2025-04-18 16:21
+
+from django.db import migrations, models
+from django.db.models import Count
+
+def remove_duplicate_channel_streams(apps, schema_editor):
+    ChannelStream = apps.get_model('dispatcharr_channels', 'ChannelStream')
+    # Find duplicates by (channel, stream)
+    duplicates = (
+        ChannelStream.objects
+        .values('channel', 'stream')
+        .annotate(count=Count('id'))
+        .filter(count__gt=1)
+    )
+
+    for dupe in duplicates:
+        # Get all duplicates for this pair
+        dups = ChannelStream.objects.filter(
+            channel=dupe['channel'],
+            stream=dupe['stream']
+        ).order_by('id')
+
+        # Keep the first one, delete the rest
+        dups.exclude(id=dups.first().id).delete()
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('dispatcharr_channels', '0015_recording_custom_properties'),
+    ]
+
+    operations = [
+        migrations.RunPython(remove_duplicate_channel_streams),
+        migrations.AddConstraint(
+            model_name='channelstream',
+            constraint=models.UniqueConstraint(fields=('channel', 'stream'), name='unique_channel_stream'),
+        ),
+    ]

apps/channels/migrations/0017_alter_channelgroup_name.py

@@ -0,0 +1,18 @@
+# Generated by Django 5.1.6 on 2025-04-21 20:47
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('dispatcharr_channels', '0016_channelstream_unique_channel_stream'),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name='channelgroup',
+            name='name',
+            field=models.TextField(db_index=True, unique=True),
+        ),
+    ]

apps/channels/migrations/0018_channelgroupm3uaccount_custom_properties_and_more.py

@@ -0,0 +1,18 @@
+# Generated by Django 5.1.6 on 2025-04-27 14:12
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('dispatcharr_channels', '0017_alter_channelgroup_name'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='channelgroupm3uaccount',
+            name='custom_properties',
+            field=models.TextField(blank=True, null=True),
+        ),
+    ]

apps/channels/migrations/0019_channel_tvc_guide_stationid.py

@@ -0,0 +1,18 @@
+# Generated by Django 5.1.6 on 2025-05-04 00:02
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('dispatcharr_channels', '0018_channelgroupm3uaccount_custom_properties_and_more'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='channel',
+            name='tvc_guide_stationid',
+            field=models.CharField(blank=True, max_length=255, null=True),
+        ),
+    ]

apps/channels/migrations/0020_alter_channel_channel_number.py

@@ -0,0 +1,18 @@
+# Generated by Django 5.1.6 on 2025-05-15 19:37
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('dispatcharr_channels', '0019_channel_tvc_guide_stationid'),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name='channel',
+            name='channel_number',
+            field=models.FloatField(db_index=True),
+        ),
+    ]

apps/channels/migrations/0021_channel_user_level.py

@@ -0,0 +1,18 @@
+# Generated by Django 5.1.6 on 2025-05-18 14:31
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('dispatcharr_channels', '0020_alter_channel_channel_number'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='channel',
+            name='user_level',
+            field=models.IntegerField(default=0),
+        ),
+    ]

apps/channels/migrations/0022_channel_auto_created_channel_auto_created_by_and_more.py

@@ -0,0 +1,35 @@
+# Generated by Django 5.1.6 on 2025-07-13 23:08
+
+import django.db.models.deletion
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('dispatcharr_channels', '0021_channel_user_level'),
+        ('m3u', '0012_alter_m3uaccount_refresh_interval'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='channel',
+            name='auto_created',
+            field=models.BooleanField(default=False, help_text='Whether this channel was automatically created via M3U auto channel sync'),
+        ),
+        migrations.AddField(
+            model_name='channel',
+            name='auto_created_by',
+            field=models.ForeignKey(blank=True, help_text='The M3U account that auto-created this channel', null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='auto_created_channels', to='m3u.m3uaccount'),
+        ),
+        migrations.AddField(
+            model_name='channelgroupm3uaccount',
+            name='auto_channel_sync',
+            field=models.BooleanField(default=False, help_text='Automatically create/delete channels to match streams in this group'),
+        ),
+        migrations.AddField(
+            model_name='channelgroupm3uaccount',
+            name='auto_sync_channel_start',
+            field=models.FloatField(blank=True, help_text='Starting channel number for auto-created channels in this group', null=True),
+        ),
+    ]

apps/channels/migrations/0023_stream_stream_stats_stream_stream_stats_updated_at.py

@@ -0,0 +1,23 @@
+# Generated by Django 5.1.6 on 2025-07-29 02:39
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('dispatcharr_channels', '0022_channel_auto_created_channel_auto_created_by_and_more'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='stream',
+            name='stream_stats',
+            field=models.JSONField(blank=True, help_text='JSON object containing stream statistics like video codec, resolution, etc.', null=True),
+        ),
+        migrations.AddField(
+            model_name='stream',
+            name='stream_stats_updated_at',
+            field=models.DateTimeField(blank=True, db_index=True, help_text='When stream statistics were last updated', null=True),
+        ),
+    ]

apps/channels/migrations/0024_alter_channelgroupm3uaccount_channel_group.py

@@ -0,0 +1,19 @@
+# Generated by Django 5.2.4 on 2025-08-22 20:14
+
+import django.db.models.deletion
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('dispatcharr_channels', '0023_stream_stream_stats_stream_stream_stats_updated_at'),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name='channelgroupm3uaccount',
+            name='channel_group',
+            field=models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='m3u_accounts', to='dispatcharr_channels.channelgroup'),
+        ),
+    ]

apps/channels/migrations/0025_alter_channelgroupm3uaccount_custom_properties_and_more.py

@@ -0,0 +1,28 @@
+# Generated by Django 5.2.4 on 2025-09-02 14:30
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('dispatcharr_channels', '0024_alter_channelgroupm3uaccount_channel_group'),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name='channelgroupm3uaccount',
+            name='custom_properties',
+            field=models.JSONField(blank=True, default=dict, null=True),
+        ),
+        migrations.AlterField(
+            model_name='recording',
+            name='custom_properties',
+            field=models.JSONField(blank=True, default=dict, null=True),
+        ),
+        migrations.AlterField(
+            model_name='stream',
+            name='custom_properties',
+            field=models.JSONField(blank=True, default=dict, null=True),
+        ),
+    ]

apps/channels/migrations/0026_recurringrecordingrule.py

@@ -0,0 +1,31 @@
+# Generated by Django 5.0.14 on 2025-09-18 14:56
+
+import django.db.models.deletion
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('dispatcharr_channels', '0025_alter_channelgroupm3uaccount_custom_properties_and_more'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='RecurringRecordingRule',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('days_of_week', models.JSONField(default=list)),
+                ('start_time', models.TimeField()),
+                ('end_time', models.TimeField()),
+                ('enabled', models.BooleanField(default=True)),
+                ('name', models.CharField(blank=True, max_length=255)),
+                ('created_at', models.DateTimeField(auto_now_add=True)),
+                ('updated_at', models.DateTimeField(auto_now=True)),
+                ('channel', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='recurring_rules', to='dispatcharr_channels.channel')),
+            ],
+            options={
+                'ordering': ['channel', 'start_time'],
+            },
+        ),
+    ]

apps/channels/migrations/0027_recurringrecordingrule_end_date_and_more.py

@@ -0,0 +1,23 @@
+# Generated by Django 5.2.4 on 2025-10-05 20:50
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('dispatcharr_channels', '0026_recurringrecordingrule'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='recurringrecordingrule',
+            name='end_date',
+            field=models.DateField(blank=True, null=True),
+        ),
+        migrations.AddField(
+            model_name='recurringrecordingrule',
+            name='start_date',
+            field=models.DateField(blank=True, null=True),
+        ),
+    ]

apps/channels/migrations/0028_channel_created_at_channel_updated_at.py

@@ -0,0 +1,25 @@
+# Generated by Django 5.2.4 on 2025-10-06 22:55
+
+import django.utils.timezone
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('dispatcharr_channels', '0027_recurringrecordingrule_end_date_and_more'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='channel',
+            name='created_at',
+            field=models.DateTimeField(auto_now_add=True, default=django.utils.timezone.now, help_text='Timestamp when this channel was created'),
+            preserve_default=False,
+        ),
+        migrations.AddField(
+            model_name='channel',
+            name='updated_at',
+            field=models.DateTimeField(auto_now=True, help_text='Timestamp when this channel was last updated'),
+        ),
+    ]

apps/channels/migrations/0029_backfill_custom_stream_hashes.py

@@ -0,0 +1,54 @@
+# Generated migration to backfill stream_hash for existing custom streams
+
+from django.db import migrations
+import hashlib
+
+
+def backfill_custom_stream_hashes(apps, schema_editor):
+    """
+    Generate stream_hash for all custom streams that don't have one.
+    Uses stream ID to create a stable hash that won't change when name/url is edited.
+    """
+    Stream = apps.get_model('dispatcharr_channels', 'Stream')
+
+    custom_streams_without_hash = Stream.objects.filter(
+        is_custom=True,
+        stream_hash__isnull=True
+    )
+
+    updated_count = 0
+    for stream in custom_streams_without_hash:
+        # Generate a stable hash using the stream's ID
+        # This ensures the hash never changes even if name/url is edited
+        unique_string = f"custom_stream_{stream.id}"
+        stream.stream_hash = hashlib.sha256(unique_string.encode()).hexdigest()
+        stream.save(update_fields=['stream_hash'])
+        updated_count += 1
+
+    if updated_count > 0:
+        print(f"Backfilled stream_hash for {updated_count} custom streams")
+    else:
+        print("No custom streams needed stream_hash backfill")
+
+
+def reverse_backfill(apps, schema_editor):
+    """
+    Reverse migration - clear stream_hash for custom streams.
+    Note: This will break preview functionality for custom streams.
+    """
+    Stream = apps.get_model('dispatcharr_channels', 'Stream')
+
+    custom_streams = Stream.objects.filter(is_custom=True)
+    count = custom_streams.update(stream_hash=None)
+    print(f"Cleared stream_hash for {count} custom streams")
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('dispatcharr_channels', '0028_channel_created_at_channel_updated_at'),
+    ]
+
+    operations = [
+        migrations.RunPython(backfill_custom_stream_hashes, reverse_backfill),
+    ]

apps/channels/migrations/0030_alter_stream_url.py

@@ -0,0 +1,18 @@
+# Generated by Django 5.2.4 on 2025-10-28 20:00
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('dispatcharr_channels', '0029_backfill_custom_stream_hashes'),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name='stream',
+            name='url',
+            field=models.URLField(blank=True, max_length=4096, null=True),
+        ),
+    ]

apps/channels/migrations/0031_channelgroupm3uaccount_is_stale_and_more.py

@@ -0,0 +1,29 @@
+# Generated by Django 5.2.9 on 2026-01-09 18:19
+
+import django.utils.timezone
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('dispatcharr_channels', '0030_alter_stream_url'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='channelgroupm3uaccount',
+            name='is_stale',
+            field=models.BooleanField(db_index=True, default=False, help_text='Whether this group relationship is stale (not seen in recent refresh, pending deletion)'),
+        ),
+        migrations.AddField(
+            model_name='channelgroupm3uaccount',
+            name='last_seen',
+            field=models.DateTimeField(db_index=True, default=django.utils.timezone.now, help_text='Last time this group was seen in the M3U source during a refresh'),
+        ),
+        migrations.AddField(
+            model_name='stream',
+            name='is_stale',
+            field=models.BooleanField(db_index=True, default=False, help_text='Whether this stream is stale (not seen in recent refresh, pending deletion)'),
+        ),
+    ]

apps/channels/migrations/0032_channel_is_adult_stream_is_adult.py

@@ -0,0 +1,23 @@
+# Generated by Django 5.2.9 on 2026-01-17 16:56
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('dispatcharr_channels', '0031_channelgroupm3uaccount_is_stale_and_more'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='channel',
+            name='is_adult',
+            field=models.BooleanField(db_index=True, default=False, help_text='Whether this channel contains adult content'),
+        ),
+        migrations.AddField(
+            model_name='stream',
+            name='is_adult',
+            field=models.BooleanField(db_index=True, default=False, help_text='Whether this stream contains adult content'),
+        ),
+    ]

apps/channels/migrations/0033_stream_id_stream_chno.py

@@ -0,0 +1,205 @@
+# Generated by Django - Add stream_id and channel_number fields with data migration
+
+from django.db import migrations, models
+import hashlib
+import json
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+def populate_fields_and_rehash(apps, schema_editor):
+    """
+    Populate stream_id and stream_chno from custom_properties for XC account streams,
+    populate stream_chno from tvg-chno for standard M3U accounts,
+    then rehash XC streams using stable hash keys.
+    """
+    Stream = apps.get_model('dispatcharr_channels', 'Stream')
+    M3UAccount = apps.get_model('m3u', 'M3UAccount')
+    CoreSettings = apps.get_model('core', 'CoreSettings')
+
+    # Get hash keys from settings
+    try:
+        stream_settings = CoreSettings.objects.get(key='stream_settings')
+        hash_key_str = stream_settings.value.get('m3u_hash_key', '') if stream_settings.value else ''
+        keys = [k.strip() for k in hash_key_str.split(',') if k.strip()] if hash_key_str else []
+    except CoreSettings.DoesNotExist:
+        keys = []
+
+    logger.info(f"Using hash keys: {keys}")
+
+    # Get XC account IDs
+    xc_account_ids = set(
+        M3UAccount.objects.filter(account_type='XC').values_list('id', flat=True)
+    )
+
+    logger.info(f"Found {len(xc_account_ids)} XC accounts")
+
+    # Track hash collisions for XC streams
+    hash_map = {}  # new_hash -> stream_id
+    duplicates_to_delete = []
+
+    # Process all streams in batches
+    batch_size = 1000
+    processed = 0
+    updated = 0
+
+    total_count = Stream.objects.count()
+    logger.info(f"Processing {total_count} total streams")
+
+    streams_to_update = []
+
+    for stream in Stream.objects.select_related('channel_group', 'm3u_account').iterator(chunk_size=batch_size):
+        processed += 1
+        needs_update = False
+
+        custom_props = stream.custom_properties or {}
+        is_xc = stream.m3u_account_id in xc_account_ids if stream.m3u_account_id else False
+
+        # Extract stream_id (XC accounts only)
+        if is_xc and isinstance(custom_props, dict):
+            provider_stream_id = custom_props.get('stream_id')
+            if provider_stream_id:
+                try:
+                    stream.stream_id = int(provider_stream_id)
+                    needs_update = True
+                except (ValueError, TypeError):
+                    pass
+
+        # Extract stream_chno
+        channel_num = None
+        if isinstance(custom_props, dict):
+            if is_xc:
+                # XC accounts use 'num'
+                channel_num = custom_props.get('num')
+            else:
+                # Standard M3U accounts use 'tvg-chno' or 'channel-number' (case insensitive check)
+                for key in ['tvg-chno', 'TVG-CHNO', 'tvg-Chno', 'Tvg-Chno', 'channel-number', 'Channel-Number', 'CHANNEL-NUMBER']:
+                    if key in custom_props:
+                        channel_num = custom_props.get(key)
+                        break
+
+        if channel_num is not None:
+            try:
+                stream.stream_chno = float(channel_num)
+                needs_update = True
+            except (ValueError, TypeError):
+                pass
+
+        # Rehash XC streams only when 'url' is in hash keys (otherwise hash wouldn't change)
+        if is_xc and stream.stream_id and keys and 'url' in keys:
+            # For XC accounts, use stream_id instead of url when 'url' is in the hash keys
+            # This ensures credential/URL changes don't break stream identity
+            effective_url = stream.stream_id
+
+            # Get group name
+            group_name = stream.channel_group.name if stream.channel_group else None
+
+            # Build hash parts
+            stream_parts = {
+                "name": stream.name,
+                "url": effective_url,
+                "tvg_id": stream.tvg_id,
+                "m3u_id": stream.m3u_account_id,
+                "group": group_name
+            }
+            hash_parts = {key: stream_parts[key] for key in keys if key in stream_parts}
+
+            # When using stream_id instead of URL, we MUST include m3u_id to prevent
+            # collisions across different XC accounts (stream_id is only unique per account)
+            if 'm3u_id' not in hash_parts:
+                hash_parts['m3u_id'] = stream.m3u_account_id
+
+            # Generate hash
+            serialized_obj = json.dumps(hash_parts, sort_keys=True)
+            new_hash = hashlib.sha256(serialized_obj.encode()).hexdigest()
+
+            # Check for collisions
+            if new_hash in hash_map:
+                # Duplicate - mark for deletion (keep the first one)
+                duplicates_to_delete.append(stream.id)
+                continue
+
+            hash_map[new_hash] = stream.id
+            stream.stream_hash = new_hash
+            needs_update = True
+
+        if needs_update:
+            streams_to_update.append(stream)
+            updated += 1
+
+        # Bulk update in batches
+        if len(streams_to_update) >= batch_size:
+            Stream.objects.bulk_update(
+                streams_to_update,
+                ['stream_id', 'stream_chno', 'stream_hash'],
+                batch_size=500
+            )
+            logger.info(f"Updated batch: {processed}/{total_count} streams processed")
+            streams_to_update = []
+
+    # Final batch
+    if streams_to_update:
+        Stream.objects.bulk_update(
+            streams_to_update,
+            ['stream_id', 'stream_chno', 'stream_hash'],
+            batch_size=500
+        )
+
+    # Delete duplicates if any
+    if duplicates_to_delete:
+        logger.warning(f"Deleting {len(duplicates_to_delete)} duplicate streams due to hash collisions")
+        Stream.objects.filter(id__in=duplicates_to_delete).delete()
+
+    logger.info(f"Migration complete: {updated} streams updated, {len(duplicates_to_delete)} duplicates removed")
+
+
+def reverse_migration(apps, schema_editor):
+    """
+    Reverse migration - clear fields but don't attempt to reverse hash changes.
+    """
+    Stream = apps.get_model('dispatcharr_channels', 'Stream')
+    Stream.objects.all().update(stream_id=None, stream_chno=None)
+    logger.info("Cleared stream_id and stream_chno fields. Note: stream hashes were not reverted.")
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('dispatcharr_channels', '0032_channel_is_adult_stream_is_adult'),
+        ('m3u', '0018_add_profile_custom_properties'),
+        ('core', '0020_change_coresettings_value_to_jsonfield'),
+    ]
+
+    operations = [
+        # Schema changes - add fields WITHOUT indexes first
+        migrations.AddField(
+            model_name='stream',
+            name='stream_id',
+            field=models.IntegerField(
+                blank=True,
+                help_text='Provider stream ID (e.g., XC stream_id) for stable identity across credential changes',
+                null=True,
+            ),
+        ),
+        migrations.AddField(
+            model_name='stream',
+            name='stream_chno',
+            field=models.FloatField(
+                blank=True,
+                help_text='Provider channel number (XC num or M3U tvg-chno) for ordering - supports decimals like 2.1',
+                null=True,
+            ),
+        ),
+        # Data migration (may delete duplicates, which would conflict with pending index creation)
+        migrations.RunPython(populate_fields_and_rehash, reverse_migration),
+        # Add indexes AFTER data migration completes
+        migrations.AddIndex(
+            model_name='stream',
+            index=models.Index(fields=['stream_id'], name='dispatcharr_stream_id_idx'),
+        ),
+        migrations.AddIndex(
+            model_name='stream',
+            index=models.Index(fields=['stream_chno'], name='dispatcharr_stream_chno_idx'),
+        ),
+    ]

apps/channels/migrations/0034_remove_stream_dispatcharr_stream_id_idx_and_more.py

@@ -0,0 +1,31 @@
+# Generated by Django 5.2.9 on 2026-02-01 03:21
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('dispatcharr_channels', '0033_stream_id_stream_chno'),
+    ]
+
+    operations = [
+        migrations.RemoveIndex(
+            model_name='stream',
+            name='dispatcharr_stream_id_idx',
+        ),
+        migrations.RemoveIndex(
+            model_name='stream',
+            name='dispatcharr_stream_chno_idx',
+        ),
+        migrations.AlterField(
+            model_name='stream',
+            name='stream_chno',
+            field=models.FloatField(blank=True, db_index=True, help_text='Provider channel number (XC num or M3U tvg-chno) for ordering - supports decimals like 2.1', null=True),
+        ),
+        migrations.AlterField(
+            model_name='stream',
+            name='stream_id',
+            field=models.IntegerField(blank=True, db_index=True, help_text='Provider stream ID (e.g., XC stream_id) for stable identity across credential changes', null=True),
+        ),
+    ]

apps/channels/models.py

@@ -0,0 +1,988 @@
+from django.db import models
+from django.core.exceptions import ValidationError
+from django.conf import settings
+from core.models import StreamProfile, CoreSettings
+from core.utils import RedisClient
+from apps.proxy.ts_proxy.redis_keys import RedisKeys
+from apps.proxy.ts_proxy.constants import ChannelMetadataField
+import logging
+import uuid
+from django.utils import timezone
+import hashlib
+import json
+from apps.epg.models import EPGData
+from apps.accounts.models import User
+
+logger = logging.getLogger(__name__)
+
+# If you have an M3UAccount model in apps.m3u, you can still import it:
+from apps.m3u.models import M3UAccount
+
+
+# Add fallback functions if Redis isn't available
+def get_total_viewers(channel_id):
+    """Get viewer count from Redis or return 0 if Redis isn't available"""
+    redis_client = RedisClient.get_client()
+
+    try:
+        return int(redis_client.get(f"channel:{channel_id}:viewers") or 0)
+    except Exception:
+        return 0
+
+
+class ChannelGroup(models.Model):
+    name = models.TextField(unique=True, db_index=True)
+
+    def related_channels(self):
+        # local import if needed to avoid cyc. Usually fine in a single file though
+        return Channel.objects.filter(channel_group=self)
+
+    def __str__(self):
+        return self.name
+
+    @classmethod
+    def bulk_create_and_fetch(cls, objects):
+        # Perform the bulk create operation
+        cls.objects.bulk_create(objects)
+
+        # Use a unique field to fetch the created objects (assuming 'name' is unique)
+        created_objects = cls.objects.filter(name__in=[obj.name for obj in objects])
+
+        return created_objects
+
+
+class Stream(models.Model):
+    """
+    Represents a single stream (e.g. from an M3U source or custom URL).
+    """
+
+    name = models.CharField(max_length=255, default="Default Stream")
+    url = models.URLField(max_length=4096, blank=True, null=True)
+    m3u_account = models.ForeignKey(
+        M3UAccount,
+        on_delete=models.CASCADE,
+        null=True,
+        blank=True,
+        related_name="streams",
+    )
+    logo_url = models.TextField(blank=True, null=True)
+    tvg_id = models.CharField(max_length=255, blank=True, null=True)
+    local_file = models.FileField(upload_to="uploads/", blank=True, null=True)
+    current_viewers = models.PositiveIntegerField(default=0)
+    updated_at = models.DateTimeField(auto_now=True)
+    channel_group = models.ForeignKey(
+        ChannelGroup,
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+        related_name="streams",
+    )
+    stream_profile = models.ForeignKey(
+        StreamProfile,
+        null=True,
+        blank=True,
+        on_delete=models.SET_NULL,
+        related_name="streams",
+    )
+    is_custom = models.BooleanField(
+        default=False,
+        help_text="Whether this is a user-created stream or from an M3U account",
+    )
+    stream_hash = models.CharField(
+        max_length=255,
+        null=True,
+        unique=True,
+        help_text="Unique hash for this stream from the M3U account",
+        db_index=True,
+    )
+    last_seen = models.DateTimeField(db_index=True, default=timezone.now)
+    is_stale = models.BooleanField(
+        default=False,
+        db_index=True,
+        help_text="Whether this stream is stale (not seen in recent refresh, pending deletion)"
+    )
+    is_adult = models.BooleanField(
+        default=False,
+        db_index=True,
+        help_text="Whether this stream contains adult content"
+    )
+    custom_properties = models.JSONField(default=dict, blank=True, null=True)
+
+    stream_id = models.IntegerField(
+        null=True,
+        blank=True,
+        db_index=True,
+        help_text="Provider stream ID (e.g., XC stream_id) for stable identity across credential changes"
+    )
+    stream_chno = models.FloatField(
+        null=True,
+        blank=True,
+        db_index=True,
+        help_text="Provider channel number (XC num or M3U tvg-chno) for ordering - supports decimals like 2.1"
+    )
+
+    # Stream statistics fields
+    stream_stats = models.JSONField(
+        null=True,
+        blank=True,
+        help_text="JSON object containing stream statistics like video codec, resolution, etc."
+    )
+    stream_stats_updated_at = models.DateTimeField(
+        null=True,
+        blank=True,
+        help_text="When stream statistics were last updated",
+        db_index=True
+    )
+
+    class Meta:
+        # If you use m3u_account, you might do unique_together = ('name','url','m3u_account')
+        verbose_name = "Stream"
+        verbose_name_plural = "Streams"
+        ordering = ["-updated_at"]
+
+    def __str__(self):
+        return self.name or self.url or f"Stream ID {self.id}"
+
+    @classmethod
+    def generate_hash_key(cls, name, url, tvg_id, keys=None, m3u_id=None, group=None,
+                          account_type=None, stream_id=None):
+        if keys is None:
+            keys = CoreSettings.get_m3u_hash_key().split(",")
+
+        # For XC accounts, use stream_id instead of url when 'url' is in the hash keys
+        # This ensures credential/URL changes don't break stream identity
+        effective_url = url
+        use_stream_id = account_type == 'XC' and stream_id and 'url' in keys
+        if use_stream_id:
+            effective_url = stream_id
+
+        stream_parts = {"name": name, "url": effective_url, "tvg_id": tvg_id, "m3u_id": m3u_id, "group": group}
+
+        hash_parts = {key: stream_parts[key] for key in keys if key in stream_parts}
+
+        # When using stream_id instead of URL, we MUST include m3u_id to prevent
+        # collisions across different XC accounts (stream_id is only unique per account)
+        if use_stream_id and 'm3u_id' not in hash_parts:
+            hash_parts['m3u_id'] = m3u_id
+
+        # Serialize and hash the dictionary
+        serialized_obj = json.dumps(
+            hash_parts, sort_keys=True
+        )  # sort_keys ensures consistent ordering
+        hash_object = hashlib.sha256(serialized_obj.encode())
+        return hash_object.hexdigest()
+
+    @classmethod
+    def update_or_create_by_hash(cls, hash_value, **fields_to_update):
+        try:
+            # Try to find the Stream object with the given hash
+            stream = cls.objects.get(stream_hash=hash_value)
+            # If it exists, update the fields
+            for field, value in fields_to_update.items():
+                setattr(stream, field, value)
+            stream.save()  # Save the updated object
+            return stream, False  # False means it was updated, not created
+        except cls.DoesNotExist:
+            # If it doesn't exist, create a new object with the given hash
+            fields_to_update["stream_hash"] = (
+                hash_value  # Make sure the hash field is set
+            )
+            stream = cls.objects.create(**fields_to_update)
+            return stream, True  # True means it was created
+
+    def get_stream_profile(self):
+        """
+        Get the stream profile for this stream.
+        Uses the stream's own profile if set, otherwise returns the default.
+        """
+        if self.stream_profile:
+            return self.stream_profile
+
+        stream_profile = StreamProfile.objects.get(
+            id=CoreSettings.get_default_stream_profile_id()
+        )
+
+        return stream_profile
+
+    def get_stream(self, requester=None):
+        """
+        Finds an available profile for this stream and reserves a connection slot.
+
+        Returns:
+            Tuple[Optional[int], Optional[int], Optional[str]]: (stream_id, profile_id, error_reason)
+        """
+        redis_client = RedisClient.get_client()
+        profile_id = redis_client.get(f"stream_profile:{self.id}")
+        if profile_id:
+            profile_id = int(profile_id)
+            return self.id, profile_id, None
+
+        # Retrieve the M3U account associated with the stream.
+        m3u_account = self.m3u_account
+        m3u_profiles = m3u_account.profiles.all()
+        default_profile = next((obj for obj in m3u_profiles if obj.is_default), None)
+        profiles = [default_profile] + [
+            obj for obj in m3u_profiles if not obj.is_default
+        ]
+
+        for profile in profiles:
+            logger.info(profile)
+            # Skip inactive profiles
+            if profile.is_active == False:
+                continue
+
+            # Atomic slot reservation: INCR first, check, rollback if over capacity
+            if profile.max_streams == 0:
+                reserved = True
+            else:
+                profile_connections_key = f"profile_connections:{profile.id}"
+                new_count = redis_client.incr(profile_connections_key)
+                if new_count <= profile.max_streams:
+                    reserved = True
+                else:
+                    redis_client.decr(profile_connections_key)
+                    reserved = False
+
+            if reserved:
+                redis_client.set(f"channel_stream:{self.id}", self.id)
+                redis_client.set(f"stream_profile:{self.id}", profile.id)
+                return self.id, profile.id, None
+
+        return None, None, "All active M3U profiles have reached maximum connection limits"
+
+    def release_stream(self):
+        """
+        Called when a stream is finished to release the lock.
+
+        Returns:
+            bool: True if stream was successfully released, False if
+                  no profile info could be found for cleanup.
+        """
+        redis_client = RedisClient.get_client()
+
+        stream_id = self.id
+        # Get the matched profile for cleanup
+        profile_id = redis_client.get(f"stream_profile:{stream_id}")
+        if not profile_id:
+            logger.debug(
+                f"Stream {stream_id}: no profile found in "
+                f"stream_profile:{stream_id}"
+            )
+            return False
+
+        redis_client.delete(f"stream_profile:{stream_id}")  # Remove profile association
+
+        profile_id = int(profile_id)
+        logger.debug(
+            f"Stream {stream_id}: found profile_id={profile_id}"
+        )
+
+        profile_connections_key = f"profile_connections:{profile_id}"
+
+        # Only decrement if the profile had a max_connections limit
+        current_count = int(redis_client.get(profile_connections_key) or 0)
+        if current_count > 0:
+            redis_client.decr(profile_connections_key)
+
+        return True
+
+
+class ChannelManager(models.Manager):
+    def active(self):
+        return self.all()
+
+
+class Channel(models.Model):
+    channel_number = models.FloatField(db_index=True)
+    name = models.CharField(max_length=255)
+    logo = models.ForeignKey(
+        "Logo",
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+        related_name="channels",
+    )
+
+    # M2M to Stream now in the same file
+    streams = models.ManyToManyField(
+        Stream, blank=True, through="ChannelStream", related_name="channels"
+    )
+
+    channel_group = models.ForeignKey(
+        "ChannelGroup",
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+        related_name="channels",
+        help_text="Channel group this channel belongs to.",
+    )
+    tvg_id = models.CharField(max_length=255, blank=True, null=True)
+    tvc_guide_stationid = models.CharField(max_length=255, blank=True, null=True)
+
+    epg_data = models.ForeignKey(
+        EPGData,
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+        related_name="channels",
+    )
+
+    stream_profile = models.ForeignKey(
+        StreamProfile,
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+        related_name="channels",
+    )
+
+    uuid = models.UUIDField(
+        default=uuid.uuid4, editable=False, unique=True, db_index=True
+    )
+
+    user_level = models.IntegerField(default=0)
+
+    is_adult = models.BooleanField(
+        default=False,
+        db_index=True,
+        help_text="Whether this channel contains adult content"
+    )
+
+    auto_created = models.BooleanField(
+        default=False,
+        help_text="Whether this channel was automatically created via M3U auto channel sync"
+    )
+    auto_created_by = models.ForeignKey(
+        "m3u.M3UAccount",
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+        related_name="auto_created_channels",
+        help_text="The M3U account that auto-created this channel"
+    )
+
+    created_at = models.DateTimeField(
+        auto_now_add=True,
+        help_text="Timestamp when this channel was created"
+    )
+    updated_at = models.DateTimeField(
+        auto_now=True,
+        help_text="Timestamp when this channel was last updated"
+    )
+
+    def clean(self):
+        # Enforce unique channel_number within a given group
+        existing = Channel.objects.filter(
+            channel_number=self.channel_number, channel_group=self.channel_group
+        ).exclude(id=self.id)
+        if existing.exists():
+            raise ValidationError(
+                f"Channel number {self.channel_number} already exists in group {self.channel_group}."
+            )
+
+    def __str__(self):
+        return f"{self.channel_number} - {self.name}"
+
+    @classmethod
+    def get_next_available_channel_number(cls, starting_from=1):
+        used_numbers = set(cls.objects.all().values_list("channel_number", flat=True))
+        n = starting_from
+        while n in used_numbers:
+            n += 1
+        return n
+
+    # @TODO: honor stream's stream profile
+    def get_stream_profile(self):
+        stream_profile = self.stream_profile
+        if not stream_profile:
+            stream_profile = StreamProfile.objects.get(
+                id=CoreSettings.get_default_stream_profile_id()
+            )
+
+        return stream_profile
+
+    def _account_active_connections(self, redis_client, m3u_account, cache: dict[int, int]) -> int:
+        """
+        Return active connection count for an M3U account across all its active profiles.
+        Uses Redis `profile_connections:*`, which is shared by live and VOD proxy paths.
+        """
+        if not m3u_account:
+            return 0
+        account_id = int(m3u_account.id)
+        if account_id in cache:
+            return cache[account_id]
+
+        total = 0
+        try:
+            for profile in m3u_account.profiles.filter(is_active=True):
+                total += int(redis_client.get(f"profile_connections:{profile.id}") or 0)
+        except Exception:
+            total = 0
+        cache[account_id] = total
+        return total
+
+    def _pick_channel_to_preempt(
+        self,
+        profile_id,
+        requester_level,
+        redis_client,
+        exclude_channel_ids=None,
+        cooldown_seconds=30,
+    ):
+        """
+        Pick the lowest-impact channel to terminate on the given profile.
+        Returns: Optional[int] channel_id to preempt
+        """
+        exclude_channel_ids = set(exclude_channel_ids or [])
+        candidates = []
+
+        # 1) Try to get active channel IDs for this profile from an index set if available
+        ch_set_key = f"ts_proxy:profile:{profile_id}:channels"
+        try:
+            ch_ids = { (int(x) if not isinstance(x, int) else x) for x in (redis_client.smembers(ch_set_key) or set()) }
+        except Exception:
+            ch_ids = set()
+
+        logger.debug("Candidate channels for preemption:")
+        logger.debug(ch_ids)
+
+        # 2) Fallback: scan metadata keys and filter by m3u_profile == profile_id
+        if not ch_ids:
+            cursor = 0
+            pattern = "ts_proxy:channel:*:metadata"
+            while True:
+                cursor, keys = redis_client.scan(cursor=cursor, match=pattern, count=500)
+                if keys:
+                    # Prefer HGET m3u_profile if metadata is a hash
+                    pipe = redis_client.pipeline()
+                    for k in keys:
+                        pipe.hget(k, "m3u_profile")
+                    prof_vals = pipe.execute()
+                    for k, prof_val in zip(keys, prof_vals):
+                        try:
+                            pid = int(prof_val) if prof_val is not None else None
+                        except Exception:
+                            pid = None
+
+                        if pid == profile_id:
+                            parts = k.split(":")  # ts_proxy:channel:{id}:metadata
+                            if len(parts) >= 4:
+                                try:
+                                    ch_ids.add(int(parts[2]))
+                                except Exception:
+                                    pass
+                if cursor == 0:
+                    break
+
+        logger.debug("Candidate channels for preemption:")
+        logger.debug(ch_ids)
+
+        if not ch_ids:
+            return None
+
+        # 3) Score candidates
+        for ch_id in ch_ids:
+            if ch_id in exclude_channel_ids:
+                continue
+
+            # Skip if recently preempted
+            last_preempt_key = f"ts_proxy:channel:{ch_id}:last_preempt"
+            try:
+                last_preempt = float(redis_client.get(last_preempt_key) or 0.0)
+            except Exception:
+                last_preempt = 0.0
+            if last_preempt and (time.time() - last_preempt) < cooldown_seconds:
+                continue
+
+            # Clients and their levels
+            clients_key = f"ts_proxy:channel:{ch_id}:clients"
+            member_ids = list(redis_client.smembers(clients_key) or [])
+            viewer_count = len(member_ids)
+            max_viewer_level = 0
+            if viewer_count:
+                pipe = redis_client.pipeline()
+                for cid in member_ids:
+                    pipe.hget(f"ts_proxy:channel:{ch_id}:clients:{cid}", "user_level")
+                levels_raw = pipe.execute()
+                levels = []
+                for lv in levels_raw:
+                    try:
+                        levels.append(int(lv or 0))
+                    except Exception:
+                        levels.append(0)
+                max_viewer_level = max(levels or [0])
+
+            # Only preempt if requester strictly outranks this channel's viewers
+            if requester_level <= max_viewer_level:
+                continue
+
+            # Metadata (protected/recording/started_at_ts)
+            meta_key = f"ts_proxy:channel:{ch_id}:metadata"
+            try:
+                protected, recording, started_at_ts = redis_client.hmget(
+                    meta_key, "protected", "recording", "started_at_ts"
+                )
+            except Exception:
+                protected = recording = started_at_ts = None
+
+            protected = str(protected or "0") in ("1", "true", "True")
+            recording = str(recording or "0") in ("1", "true", "True")
+            if protected or recording:
+                continue
+
+            try:
+                started_at_ts = float(started_at_ts) if started_at_ts is not None else None
+            except Exception:
+                started_at_ts = None
+            if started_at_ts is None:
+                started_at_ts = time.time()  # treat unknown as newest
+
+            # Score: lower is safer to terminate
+            has_viewers = 1 if viewer_count > 0 else 0
+            score = (has_viewers, max_viewer_level, viewer_count, started_at_ts)
+            candidates.append((score, ch_id))
+
+        logger.debug("Candidate channels after scoring:")
+        logger.debug(candidates)
+
+        if not candidates:
+            return None
+
+        candidates.sort(key=lambda x: x[0])
+        victim_id = candidates[0][1]
+
+        # Mark preempt timestamp to avoid thrashing
+        try:
+            redis_client.set(f"ts_proxy:channel:{victim_id}:last_preempt", str(time.time()), ex=3600)
+        except Exception:
+            pass
+
+        return victim_id
+
+    def _check_and_reserve_profile_slot(self, profile, redis_client):
+        """
+        Atomically check and reserve a connection slot for the given profile.
+
+        Uses an INCR-first-then-check pattern to eliminate the TOCTOU race
+        condition where separate GET + check + INCR operations could allow
+        concurrent requests to both pass the capacity check.
+
+        For profiles with max_streams=0 (unlimited), no reservation is needed.
+
+        Args:
+            profile: M3UAccountProfile instance
+            redis_client: Redis client instance
+
+        Returns:
+            tuple: (reserved: bool, current_count: int)
+        """
+        if profile.max_streams == 0:
+            return (True, 0)
+
+        profile_connections_key = f"profile_connections:{profile.id}"
+
+        # Atomically increment first — this is a single Redis command
+        new_count = redis_client.incr(profile_connections_key)
+
+        if new_count <= profile.max_streams:
+            return (True, new_count)
+
+        # Over capacity — roll back the increment
+        redis_client.decr(profile_connections_key)
+        return (False, new_count - 1)
+
+    def get_stream(self, requester=None):
+        """
+        Finds an available stream for the requested channel and returns the selected stream and profile.
+
+        Returns:
+            Tuple[Optional[int], Optional[int], Optional[str]]: (stream_id, profile_id, error_reason)
+        """
+        redis_client = RedisClient.get_client()
+        error_reason = None
+
+        # Check if this channel has any streams
+        if not self.streams.exists():
+            error_reason = "No streams assigned to channel"
+            return None, None, error_reason
+
+        # Check if a stream is already active for this channel
+        stream_id_bytes = redis_client.get(f"channel_stream:{self.id}")
+        if stream_id_bytes:
+            try:
+                stream_id = int(stream_id_bytes)
+                profile_id_bytes = redis_client.get(f"stream_profile:{stream_id}")
+                if profile_id_bytes:
+                    try:
+                        profile_id = int(profile_id_bytes)
+                        return stream_id, profile_id, None
+                    except (ValueError, TypeError):
+                        logger.debug(
+                            f"Invalid profile ID retrieved from Redis: {profile_id_bytes}"
+                        )
+            except (ValueError, TypeError):
+                logger.debug(
+                    f"Invalid stream ID retrieved from Redis: {stream_id_bytes}"
+                )
+
+        # No existing active stream, attempt to assign a new one
+        has_streams_but_maxed_out = False
+        has_active_profiles = False
+        account_load_cache: dict[int, int] = {}
+
+        ordered_streams = list(self.streams.all().order_by("channelstream__order"))
+        original_order = {stream.id: idx for idx, stream in enumerate(ordered_streams)}
+        ordered_streams.sort(
+            key=lambda s: (
+                self._account_active_connections(redis_client, s.m3u_account, account_load_cache),
+                original_order.get(s.id, 0),
+            )
+        )
+
+        # Iterate through channel streams and their profiles
+        for stream in ordered_streams:
+            # Retrieve the M3U account associated with the stream.
+            m3u_account = stream.m3u_account
+            if not m3u_account:
+                logger.debug(f"Stream {stream.id} has no M3U account")
+                continue
+            if m3u_account.is_active == False:
+                logger.debug(f"M3U account {m3u_account.id} is inactive, skipping.")
+                continue
+
+            m3u_profiles = m3u_account.profiles.filter(is_active=True)
+            default_profile = next(
+                (obj for obj in m3u_profiles if obj.is_default), None
+            )
+
+            if not default_profile:
+                logger.debug(f"M3U account {m3u_account.id} has no active default profile")
+                continue
+
+            profiles = [default_profile] + [
+                obj for obj in m3u_profiles if not obj.is_default
+            ]
+
+            for profile in profiles:
+                has_active_profiles = True
+
+                # Atomically check and reserve a slot (INCR-first pattern)
+                reserved, current_count = self._check_and_reserve_profile_slot(
+                    profile, redis_client
+                )
+
+                if reserved:
+                    # Slot reserved — assign stream to this channel
+                    redis_client.set(f"channel_stream:{self.id}", stream.id)
+                    redis_client.set(f"stream_profile:{stream.id}", profile.id)
+
+                    return (
+                        stream.id,
+                        profile.id,
+                        None,
+                    )  # Return newly assigned stream and matched profile
+                else:
+                    # At capacity: try to preempt a lower-impact channel on this profile
+                    victim_channel_id = self._pick_channel_to_preempt(
+                        profile_id=profile.id,
+                        requester_level=requester.user_level if requester else 100,
+                        redis_client=redis_client,
+                        exclude_channel_ids=None,
+                    )
+                    if victim_channel_id:
+                        logger.info(f"Preempting channel {victim_channel_id} for new stream on profile {profile.id}")
+                        # return self.id, profile.id, victim_channel_id
+
+                    # This profile is at max connections
+                    has_streams_but_maxed_out = True
+                    logger.debug(
+                        f"Profile {profile.id} at max connections: "
+                        f"{current_count}/{profile.max_streams}"
+                    )
+
+        # No available streams - determine specific reason
+        if has_streams_but_maxed_out:
+            error_reason = "All active M3U profiles have reached maximum connection limits"
+        elif has_active_profiles:
+            error_reason = "No compatible active profile found for any assigned stream"
+        else:
+            error_reason = "No active profiles found for any assigned stream"
+
+        return None, None, error_reason
+
+    def release_stream(self):
+        """
+        Called when a stream is finished to release the lock.
+
+        Returns:
+            bool: True if stream was successfully released, False if
+                  no stream/profile info could be found for cleanup.
+        """
+        redis_client = RedisClient.get_client()
+
+        stream_id = redis_client.get(f"channel_stream:{self.id}")
+        if not stream_id:
+            # Primary key missing — try metadata hash fallback.
+            # The proxy may have already cleaned up channel_stream/stream_profile
+            # keys, but the metadata hash can still have the stream_id and profile.
+            metadata_key = RedisKeys.channel_metadata(str(self.uuid))
+            meta_stream_id = redis_client.hget(
+                metadata_key, ChannelMetadataField.STREAM_ID
+            )
+            meta_profile_id = redis_client.hget(
+                metadata_key, ChannelMetadataField.M3U_PROFILE
+            )
+
+            if meta_stream_id and meta_profile_id:
+                stream_id = int(meta_stream_id)
+                profile_id = int(meta_profile_id)
+                logger.debug(
+                    f"Channel {self.uuid}: recovered stream_id={stream_id}, "
+                    f"profile_id={profile_id} from metadata fallback"
+                )
+                # Clean up any remaining keys
+                redis_client.delete(f"channel_stream:{self.id}")
+                redis_client.delete(f"stream_profile:{stream_id}")
+
+                # Clear metadata fields so duplicate release_stream() calls
+                # won't find them and DECR again
+                redis_client.hdel(
+                    metadata_key,
+                    ChannelMetadataField.STREAM_ID,
+                    ChannelMetadataField.M3U_PROFILE,
+                )
+
+                profile_connections_key = f"profile_connections:{profile_id}"
+                current_count = int(
+                    redis_client.get(profile_connections_key) or 0
+                )
+                if current_count > 0:
+                    redis_client.decr(profile_connections_key)
+                return True
+
+            logger.debug(
+                f"Channel {self.uuid}: no stream info found in primary keys "
+                f"or metadata fallback"
+            )
+            return False
+
+        redis_client.delete(f"channel_stream:{self.id}")  # Remove active stream
+
+        stream_id = int(stream_id)
+        logger.debug(
+            f"Channel {self.uuid}: found stream_id={stream_id} for "
+            f"channel_stream:{self.id}"
+        )
+
+        # Get the matched profile for cleanup
+        profile_id = redis_client.get(f"stream_profile:{stream_id}")
+        if profile_id:
+            redis_client.delete(f"stream_profile:{stream_id}")  # Remove profile association
+            profile_id = int(profile_id)
+        else:
+            # stream_profile key missing — try metadata hash fallback
+            metadata_key = RedisKeys.channel_metadata(str(self.uuid))
+            meta_profile_id = redis_client.hget(
+                metadata_key, ChannelMetadataField.M3U_PROFILE
+            )
+            if meta_profile_id:
+                profile_id = int(meta_profile_id)
+                logger.debug(
+                    f"Channel {self.uuid}: recovered profile_id={profile_id} "
+                    f"from metadata fallback (stream_profile:{stream_id} was missing)"
+                )
+            else:
+                logger.warning(
+                    f"Channel {self.uuid}: no profile found for "
+                    f"stream_profile:{stream_id} or in metadata fallback"
+                )
+                return False
+        logger.debug(
+            f"Channel {self.uuid}: found profile_id={profile_id} for "
+            f"stream {stream_id}"
+        )
+
+        profile_connections_key = f"profile_connections:{profile_id}"
+
+        # Only decrement if the profile had a max_connections limit
+        current_count = int(redis_client.get(profile_connections_key) or 0)
+        if current_count > 0:
+            redis_client.decr(profile_connections_key)
+
+        # Clear metadata fields so duplicate release_stream() calls
+        # (e.g. from _clean_redis_keys or ChannelService.stop_channel)
+        # won't find them via fallback and DECR again
+        metadata_key = RedisKeys.channel_metadata(str(self.uuid))
+        redis_client.hdel(
+            metadata_key,
+            ChannelMetadataField.STREAM_ID,
+            ChannelMetadataField.M3U_PROFILE,
+        )
+
+        return True
+
+    def update_stream_profile(self, new_profile_id):
+        """
+        Updates the profile for the current stream and adjusts connection counts.
+
+        Args:
+            new_profile_id: The ID of the new stream profile to use
+
+        Returns:
+            bool: True if successful, False otherwise
+        """
+        redis_client = RedisClient.get_client()
+
+        # Get current stream ID
+        stream_id_bytes = redis_client.get(f"channel_stream:{self.id}")
+        if not stream_id_bytes:
+            logger.debug("No active stream found for channel")
+            return False
+
+        stream_id = int(stream_id_bytes)
+
+        # Get current profile ID
+        current_profile_id_bytes = redis_client.get(f"stream_profile:{stream_id}")
+        if not current_profile_id_bytes:
+            logger.debug("No profile found for current stream")
+            return False
+
+        current_profile_id = int(current_profile_id_bytes)
+
+        # Don't do anything if the profile is already set to the requested one
+        if current_profile_id == new_profile_id:
+            return True
+
+        # Use pipeline for atomic profile switch to prevent counter drift
+        # if an exception occurs between DECR and INCR
+        old_profile_connections_key = f"profile_connections:{current_profile_id}"
+        new_profile_connections_key = f"profile_connections:{new_profile_id}"
+        old_count = int(redis_client.get(old_profile_connections_key) or 0)
+
+        pipe = redis_client.pipeline()
+        if old_count > 0:
+            pipe.decr(old_profile_connections_key)
+        pipe.set(f"stream_profile:{stream_id}", new_profile_id)
+        pipe.incr(new_profile_connections_key)
+        pipe.execute()
+        logger.info(
+            f"Updated stream {stream_id} profile from {current_profile_id} to {new_profile_id}"
+        )
+        return True
+
+
+class ChannelProfile(models.Model):
+    name = models.CharField(max_length=100, unique=True)
+
+
+class ChannelProfileMembership(models.Model):
+    channel_profile = models.ForeignKey(ChannelProfile, on_delete=models.CASCADE)
+    channel = models.ForeignKey(Channel, on_delete=models.CASCADE)
+    enabled = models.BooleanField(
+        default=True
+    )  # Track if the channel is enabled for this group
+
+    class Meta:
+        unique_together = ("channel_profile", "channel")
+
+
+class ChannelStream(models.Model):
+    channel = models.ForeignKey(Channel, on_delete=models.CASCADE)
+    stream = models.ForeignKey(Stream, on_delete=models.CASCADE)
+    order = models.PositiveIntegerField(default=0)  # Ordering field
+
+    class Meta:
+        ordering = ["order"]  # Ensure streams are retrieved in order
+        constraints = [
+            models.UniqueConstraint(
+                fields=["channel", "stream"], name="unique_channel_stream"
+            )
+        ]
+
+
+class ChannelGroupM3UAccount(models.Model):
+    channel_group = models.ForeignKey(
+        ChannelGroup, on_delete=models.CASCADE, related_name="m3u_accounts"
+    )
+    m3u_account = models.ForeignKey(
+        M3UAccount, on_delete=models.CASCADE, related_name="channel_group"
+    )
+    custom_properties = models.JSONField(default=dict, blank=True, null=True)
+    enabled = models.BooleanField(default=True)
+    auto_channel_sync = models.BooleanField(
+        default=False,
+        help_text='Automatically create/delete channels to match streams in this group'
+    )
+    auto_sync_channel_start = models.FloatField(
+        null=True,
+        blank=True,
+        help_text='Starting channel number for auto-created channels in this group'
+    )
+    last_seen = models.DateTimeField(
+        default=timezone.now,
+        db_index=True,
+        help_text='Last time this group was seen in the M3U source during a refresh'
+    )
+    is_stale = models.BooleanField(
+        default=False,
+        db_index=True,
+        help_text='Whether this group relationship is stale (not seen in recent refresh, pending deletion)'
+    )
+
+    class Meta:
+        unique_together = ("channel_group", "m3u_account")
+
+    def __str__(self):
+        return f"{self.channel_group.name} - {self.m3u_account.name} (Enabled: {self.enabled})"
+
+
+class Logo(models.Model):
+    name = models.CharField(max_length=255)
+    url = models.TextField(unique=True)
+
+    def __str__(self):
+        return self.name
+
+
+class Recording(models.Model):
+    channel = models.ForeignKey(
+        "Channel", on_delete=models.CASCADE, related_name="recordings"
+    )
+    start_time = models.DateTimeField()
+    end_time = models.DateTimeField()
+    task_id = models.CharField(max_length=255, null=True, blank=True)
+    custom_properties = models.JSONField(default=dict, blank=True, null=True)
+
+    def __str__(self):
+        return f"{self.channel.name} - {self.start_time} to {self.end_time}"
+
+
+class RecurringRecordingRule(models.Model):
+    """Rule describing a recurring manual DVR schedule."""
+
+    channel = models.ForeignKey(
+        "Channel",
+        on_delete=models.CASCADE,
+        related_name="recurring_rules",
+    )
+    days_of_week = models.JSONField(default=list)
+    start_time = models.TimeField()
+    end_time = models.TimeField()
+    enabled = models.BooleanField(default=True)
+    name = models.CharField(max_length=255, blank=True)
+    start_date = models.DateField(null=True, blank=True)
+    end_date = models.DateField(null=True, blank=True)
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+
+    class Meta:
+        ordering = ["channel", "start_time"]
+
+    def __str__(self):
+        channel_name = getattr(self.channel, "name", str(self.channel_id))
+        return f"Recurring rule for {channel_name}"
+
+    def cleaned_days(self):
+        try:
+            return sorted({int(d) for d in (self.days_of_week or []) if 0 <= int(d) <= 6})
+        except Exception:
+            return []

apps/channels/models.py.bak.1778276755

@@ -0,0 +1,958 @@
+from django.db import models
+from django.core.exceptions import ValidationError
+from django.conf import settings
+from core.models import StreamProfile, CoreSettings
+from core.utils import RedisClient
+from apps.proxy.ts_proxy.redis_keys import RedisKeys
+from apps.proxy.ts_proxy.constants import ChannelMetadataField
+import logging
+import uuid
+from django.utils import timezone
+import hashlib
+import json
+from apps.epg.models import EPGData
+from apps.accounts.models import User
+
+logger = logging.getLogger(__name__)
+
+# If you have an M3UAccount model in apps.m3u, you can still import it:
+from apps.m3u.models import M3UAccount
+
+
+# Add fallback functions if Redis isn't available
+def get_total_viewers(channel_id):
+    """Get viewer count from Redis or return 0 if Redis isn't available"""
+    redis_client = RedisClient.get_client()
+
+    try:
+        return int(redis_client.get(f"channel:{channel_id}:viewers") or 0)
+    except Exception:
+        return 0
+
+
+class ChannelGroup(models.Model):
+    name = models.TextField(unique=True, db_index=True)
+
+    def related_channels(self):
+        # local import if needed to avoid cyc. Usually fine in a single file though
+        return Channel.objects.filter(channel_group=self)
+
+    def __str__(self):
+        return self.name
+
+    @classmethod
+    def bulk_create_and_fetch(cls, objects):
+        # Perform the bulk create operation
+        cls.objects.bulk_create(objects)
+
+        # Use a unique field to fetch the created objects (assuming 'name' is unique)
+        created_objects = cls.objects.filter(name__in=[obj.name for obj in objects])
+
+        return created_objects
+
+
+class Stream(models.Model):
+    """
+    Represents a single stream (e.g. from an M3U source or custom URL).
+    """
+
+    name = models.CharField(max_length=255, default="Default Stream")
+    url = models.URLField(max_length=4096, blank=True, null=True)
+    m3u_account = models.ForeignKey(
+        M3UAccount,
+        on_delete=models.CASCADE,
+        null=True,
+        blank=True,
+        related_name="streams",
+    )
+    logo_url = models.TextField(blank=True, null=True)
+    tvg_id = models.CharField(max_length=255, blank=True, null=True)
+    local_file = models.FileField(upload_to="uploads/", blank=True, null=True)
+    current_viewers = models.PositiveIntegerField(default=0)
+    updated_at = models.DateTimeField(auto_now=True)
+    channel_group = models.ForeignKey(
+        ChannelGroup,
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+        related_name="streams",
+    )
+    stream_profile = models.ForeignKey(
+        StreamProfile,
+        null=True,
+        blank=True,
+        on_delete=models.SET_NULL,
+        related_name="streams",
+    )
+    is_custom = models.BooleanField(
+        default=False,
+        help_text="Whether this is a user-created stream or from an M3U account",
+    )
+    stream_hash = models.CharField(
+        max_length=255,
+        null=True,
+        unique=True,
+        help_text="Unique hash for this stream from the M3U account",
+        db_index=True,
+    )
+    last_seen = models.DateTimeField(db_index=True, default=timezone.now)
+    is_stale = models.BooleanField(
+        default=False,
+        db_index=True,
+        help_text="Whether this stream is stale (not seen in recent refresh, pending deletion)"
+    )
+    is_adult = models.BooleanField(
+        default=False,
+        db_index=True,
+        help_text="Whether this stream contains adult content"
+    )
+    custom_properties = models.JSONField(default=dict, blank=True, null=True)
+
+    stream_id = models.IntegerField(
+        null=True,
+        blank=True,
+        db_index=True,
+        help_text="Provider stream ID (e.g., XC stream_id) for stable identity across credential changes"
+    )
+    stream_chno = models.FloatField(
+        null=True,
+        blank=True,
+        db_index=True,
+        help_text="Provider channel number (XC num or M3U tvg-chno) for ordering - supports decimals like 2.1"
+    )
+
+    # Stream statistics fields
+    stream_stats = models.JSONField(
+        null=True,
+        blank=True,
+        help_text="JSON object containing stream statistics like video codec, resolution, etc."
+    )
+    stream_stats_updated_at = models.DateTimeField(
+        null=True,
+        blank=True,
+        help_text="When stream statistics were last updated",
+        db_index=True
+    )
+
+    class Meta:
+        # If you use m3u_account, you might do unique_together = ('name','url','m3u_account')
+        verbose_name = "Stream"
+        verbose_name_plural = "Streams"
+        ordering = ["-updated_at"]
+
+    def __str__(self):
+        return self.name or self.url or f"Stream ID {self.id}"
+
+    @classmethod
+    def generate_hash_key(cls, name, url, tvg_id, keys=None, m3u_id=None, group=None,
+                          account_type=None, stream_id=None):
+        if keys is None:
+            keys = CoreSettings.get_m3u_hash_key().split(",")
+
+        # For XC accounts, use stream_id instead of url when 'url' is in the hash keys
+        # This ensures credential/URL changes don't break stream identity
+        effective_url = url
+        use_stream_id = account_type == 'XC' and stream_id and 'url' in keys
+        if use_stream_id:
+            effective_url = stream_id
+
+        stream_parts = {"name": name, "url": effective_url, "tvg_id": tvg_id, "m3u_id": m3u_id, "group": group}
+
+        hash_parts = {key: stream_parts[key] for key in keys if key in stream_parts}
+
+        # When using stream_id instead of URL, we MUST include m3u_id to prevent
+        # collisions across different XC accounts (stream_id is only unique per account)
+        if use_stream_id and 'm3u_id' not in hash_parts:
+            hash_parts['m3u_id'] = m3u_id
+
+        # Serialize and hash the dictionary
+        serialized_obj = json.dumps(
+            hash_parts, sort_keys=True
+        )  # sort_keys ensures consistent ordering
+        hash_object = hashlib.sha256(serialized_obj.encode())
+        return hash_object.hexdigest()
+
+    @classmethod
+    def update_or_create_by_hash(cls, hash_value, **fields_to_update):
+        try:
+            # Try to find the Stream object with the given hash
+            stream = cls.objects.get(stream_hash=hash_value)
+            # If it exists, update the fields
+            for field, value in fields_to_update.items():
+                setattr(stream, field, value)
+            stream.save()  # Save the updated object
+            return stream, False  # False means it was updated, not created
+        except cls.DoesNotExist:
+            # If it doesn't exist, create a new object with the given hash
+            fields_to_update["stream_hash"] = (
+                hash_value  # Make sure the hash field is set
+            )
+            stream = cls.objects.create(**fields_to_update)
+            return stream, True  # True means it was created
+
+    def get_stream_profile(self):
+        """
+        Get the stream profile for this stream.
+        Uses the stream's own profile if set, otherwise returns the default.
+        """
+        if self.stream_profile:
+            return self.stream_profile
+
+        stream_profile = StreamProfile.objects.get(
+            id=CoreSettings.get_default_stream_profile_id()
+        )
+
+        return stream_profile
+
+    def get_stream(self, requester=None):
+        """
+        Finds an available profile for this stream and reserves a connection slot.
+
+        Returns:
+            Tuple[Optional[int], Optional[int], Optional[str]]: (stream_id, profile_id, error_reason)
+        """
+        redis_client = RedisClient.get_client()
+        profile_id = redis_client.get(f"stream_profile:{self.id}")
+        if profile_id:
+            profile_id = int(profile_id)
+            return self.id, profile_id, None
+
+        # Retrieve the M3U account associated with the stream.
+        m3u_account = self.m3u_account
+        m3u_profiles = m3u_account.profiles.all()
+        default_profile = next((obj for obj in m3u_profiles if obj.is_default), None)
+        profiles = [default_profile] + [
+            obj for obj in m3u_profiles if not obj.is_default
+        ]
+
+        for profile in profiles:
+            logger.info(profile)
+            # Skip inactive profiles
+            if profile.is_active == False:
+                continue
+
+            # Atomic slot reservation: INCR first, check, rollback if over capacity
+            if profile.max_streams == 0:
+                reserved = True
+            else:
+                profile_connections_key = f"profile_connections:{profile.id}"
+                new_count = redis_client.incr(profile_connections_key)
+                if new_count <= profile.max_streams:
+                    reserved = True
+                else:
+                    redis_client.decr(profile_connections_key)
+                    reserved = False
+
+            if reserved:
+                redis_client.set(f"channel_stream:{self.id}", self.id)
+                redis_client.set(f"stream_profile:{self.id}", profile.id)
+                return self.id, profile.id, None
+
+        return None, None, "All active M3U profiles have reached maximum connection limits"
+
+    def release_stream(self):
+        """
+        Called when a stream is finished to release the lock.
+
+        Returns:
+            bool: True if stream was successfully released, False if
+                  no profile info could be found for cleanup.
+        """
+        redis_client = RedisClient.get_client()
+
+        stream_id = self.id
+        # Get the matched profile for cleanup
+        profile_id = redis_client.get(f"stream_profile:{stream_id}")
+        if not profile_id:
+            logger.debug(
+                f"Stream {stream_id}: no profile found in "
+                f"stream_profile:{stream_id}"
+            )
+            return False
+
+        redis_client.delete(f"stream_profile:{stream_id}")  # Remove profile association
+
+        profile_id = int(profile_id)
+        logger.debug(
+            f"Stream {stream_id}: found profile_id={profile_id}"
+        )
+
+        profile_connections_key = f"profile_connections:{profile_id}"
+
+        # Only decrement if the profile had a max_connections limit
+        current_count = int(redis_client.get(profile_connections_key) or 0)
+        if current_count > 0:
+            redis_client.decr(profile_connections_key)
+
+        return True
+
+
+class ChannelManager(models.Manager):
+    def active(self):
+        return self.all()
+
+
+class Channel(models.Model):
+    channel_number = models.FloatField(db_index=True)
+    name = models.CharField(max_length=255)
+    logo = models.ForeignKey(
+        "Logo",
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+        related_name="channels",
+    )
+
+    # M2M to Stream now in the same file
+    streams = models.ManyToManyField(
+        Stream, blank=True, through="ChannelStream", related_name="channels"
+    )
+
+    channel_group = models.ForeignKey(
+        "ChannelGroup",
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+        related_name="channels",
+        help_text="Channel group this channel belongs to.",
+    )
+    tvg_id = models.CharField(max_length=255, blank=True, null=True)
+    tvc_guide_stationid = models.CharField(max_length=255, blank=True, null=True)
+
+    epg_data = models.ForeignKey(
+        EPGData,
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+        related_name="channels",
+    )
+
+    stream_profile = models.ForeignKey(
+        StreamProfile,
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+        related_name="channels",
+    )
+
+    uuid = models.UUIDField(
+        default=uuid.uuid4, editable=False, unique=True, db_index=True
+    )
+
+    user_level = models.IntegerField(default=0)
+
+    is_adult = models.BooleanField(
+        default=False,
+        db_index=True,
+        help_text="Whether this channel contains adult content"
+    )
+
+    auto_created = models.BooleanField(
+        default=False,
+        help_text="Whether this channel was automatically created via M3U auto channel sync"
+    )
+    auto_created_by = models.ForeignKey(
+        "m3u.M3UAccount",
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+        related_name="auto_created_channels",
+        help_text="The M3U account that auto-created this channel"
+    )
+
+    created_at = models.DateTimeField(
+        auto_now_add=True,
+        help_text="Timestamp when this channel was created"
+    )
+    updated_at = models.DateTimeField(
+        auto_now=True,
+        help_text="Timestamp when this channel was last updated"
+    )
+
+    def clean(self):
+        # Enforce unique channel_number within a given group
+        existing = Channel.objects.filter(
+            channel_number=self.channel_number, channel_group=self.channel_group
+        ).exclude(id=self.id)
+        if existing.exists():
+            raise ValidationError(
+                f"Channel number {self.channel_number} already exists in group {self.channel_group}."
+            )
+
+    def __str__(self):
+        return f"{self.channel_number} - {self.name}"
+
+    @classmethod
+    def get_next_available_channel_number(cls, starting_from=1):
+        used_numbers = set(cls.objects.all().values_list("channel_number", flat=True))
+        n = starting_from
+        while n in used_numbers:
+            n += 1
+        return n
+
+    # @TODO: honor stream's stream profile
+    def get_stream_profile(self):
+        stream_profile = self.stream_profile
+        if not stream_profile:
+            stream_profile = StreamProfile.objects.get(
+                id=CoreSettings.get_default_stream_profile_id()
+            )
+
+        return stream_profile
+
+    def _pick_channel_to_preempt(
+        self,
+        profile_id,
+        requester_level,
+        redis_client,
+        exclude_channel_ids=None,
+        cooldown_seconds=30,
+    ):
+        """
+        Pick the lowest-impact channel to terminate on the given profile.
+        Returns: Optional[int] channel_id to preempt
+        """
+        exclude_channel_ids = set(exclude_channel_ids or [])
+        candidates = []
+
+        # 1) Try to get active channel IDs for this profile from an index set if available
+        ch_set_key = f"ts_proxy:profile:{profile_id}:channels"
+        try:
+            ch_ids = { (int(x) if not isinstance(x, int) else x) for x in (redis_client.smembers(ch_set_key) or set()) }
+        except Exception:
+            ch_ids = set()
+
+        logger.debug("Candidate channels for preemption:")
+        logger.debug(ch_ids)
+
+        # 2) Fallback: scan metadata keys and filter by m3u_profile == profile_id
+        if not ch_ids:
+            cursor = 0
+            pattern = "ts_proxy:channel:*:metadata"
+            while True:
+                cursor, keys = redis_client.scan(cursor=cursor, match=pattern, count=500)
+                if keys:
+                    # Prefer HGET m3u_profile if metadata is a hash
+                    pipe = redis_client.pipeline()
+                    for k in keys:
+                        pipe.hget(k, "m3u_profile")
+                    prof_vals = pipe.execute()
+                    for k, prof_val in zip(keys, prof_vals):
+                        try:
+                            pid = int(prof_val) if prof_val is not None else None
+                        except Exception:
+                            pid = None
+
+                        if pid == profile_id:
+                            parts = k.split(":")  # ts_proxy:channel:{id}:metadata
+                            if len(parts) >= 4:
+                                try:
+                                    ch_ids.add(int(parts[2]))
+                                except Exception:
+                                    pass
+                if cursor == 0:
+                    break
+
+        logger.debug("Candidate channels for preemption:")
+        logger.debug(ch_ids)
+
+        if not ch_ids:
+            return None
+
+        # 3) Score candidates
+        for ch_id in ch_ids:
+            if ch_id in exclude_channel_ids:
+                continue
+
+            # Skip if recently preempted
+            last_preempt_key = f"ts_proxy:channel:{ch_id}:last_preempt"
+            try:
+                last_preempt = float(redis_client.get(last_preempt_key) or 0.0)
+            except Exception:
+                last_preempt = 0.0
+            if last_preempt and (time.time() - last_preempt) < cooldown_seconds:
+                continue
+
+            # Clients and their levels
+            clients_key = f"ts_proxy:channel:{ch_id}:clients"
+            member_ids = list(redis_client.smembers(clients_key) or [])
+            viewer_count = len(member_ids)
+            max_viewer_level = 0
+            if viewer_count:
+                pipe = redis_client.pipeline()
+                for cid in member_ids:
+                    pipe.hget(f"ts_proxy:channel:{ch_id}:clients:{cid}", "user_level")
+                levels_raw = pipe.execute()
+                levels = []
+                for lv in levels_raw:
+                    try:
+                        levels.append(int(lv or 0))
+                    except Exception:
+                        levels.append(0)
+                max_viewer_level = max(levels or [0])
+
+            # Only preempt if requester strictly outranks this channel's viewers
+            if requester_level <= max_viewer_level:
+                continue
+
+            # Metadata (protected/recording/started_at_ts)
+            meta_key = f"ts_proxy:channel:{ch_id}:metadata"
+            try:
+                protected, recording, started_at_ts = redis_client.hmget(
+                    meta_key, "protected", "recording", "started_at_ts"
+                )
+            except Exception:
+                protected = recording = started_at_ts = None
+
+            protected = str(protected or "0") in ("1", "true", "True")
+            recording = str(recording or "0") in ("1", "true", "True")
+            if protected or recording:
+                continue
+
+            try:
+                started_at_ts = float(started_at_ts) if started_at_ts is not None else None
+            except Exception:
+                started_at_ts = None
+            if started_at_ts is None:
+                started_at_ts = time.time()  # treat unknown as newest
+
+            # Score: lower is safer to terminate
+            has_viewers = 1 if viewer_count > 0 else 0
+            score = (has_viewers, max_viewer_level, viewer_count, started_at_ts)
+            candidates.append((score, ch_id))
+
+        logger.debug("Candidate channels after scoring:")
+        logger.debug(candidates)
+
+        if not candidates:
+            return None
+
+        candidates.sort(key=lambda x: x[0])
+        victim_id = candidates[0][1]
+
+        # Mark preempt timestamp to avoid thrashing
+        try:
+            redis_client.set(f"ts_proxy:channel:{victim_id}:last_preempt", str(time.time()), ex=3600)
+        except Exception:
+            pass
+
+        return victim_id
+
+    def _check_and_reserve_profile_slot(self, profile, redis_client):
+        """
+        Atomically check and reserve a connection slot for the given profile.
+
+        Uses an INCR-first-then-check pattern to eliminate the TOCTOU race
+        condition where separate GET + check + INCR operations could allow
+        concurrent requests to both pass the capacity check.
+
+        For profiles with max_streams=0 (unlimited), no reservation is needed.
+
+        Args:
+            profile: M3UAccountProfile instance
+            redis_client: Redis client instance
+
+        Returns:
+            tuple: (reserved: bool, current_count: int)
+        """
+        if profile.max_streams == 0:
+            return (True, 0)
+
+        profile_connections_key = f"profile_connections:{profile.id}"
+
+        # Atomically increment first — this is a single Redis command
+        new_count = redis_client.incr(profile_connections_key)
+
+        if new_count <= profile.max_streams:
+            return (True, new_count)
+
+        # Over capacity — roll back the increment
+        redis_client.decr(profile_connections_key)
+        return (False, new_count - 1)
+
+    def get_stream(self, requester=None):
+        """
+        Finds an available stream for the requested channel and returns the selected stream and profile.
+
+        Returns:
+            Tuple[Optional[int], Optional[int], Optional[str]]: (stream_id, profile_id, error_reason)
+        """
+        redis_client = RedisClient.get_client()
+        error_reason = None
+
+        # Check if this channel has any streams
+        if not self.streams.exists():
+            error_reason = "No streams assigned to channel"
+            return None, None, error_reason
+
+        # Check if a stream is already active for this channel
+        stream_id_bytes = redis_client.get(f"channel_stream:{self.id}")
+        if stream_id_bytes:
+            try:
+                stream_id = int(stream_id_bytes)
+                profile_id_bytes = redis_client.get(f"stream_profile:{stream_id}")
+                if profile_id_bytes:
+                    try:
+                        profile_id = int(profile_id_bytes)
+                        return stream_id, profile_id, None
+                    except (ValueError, TypeError):
+                        logger.debug(
+                            f"Invalid profile ID retrieved from Redis: {profile_id_bytes}"
+                        )
+            except (ValueError, TypeError):
+                logger.debug(
+                    f"Invalid stream ID retrieved from Redis: {stream_id_bytes}"
+                )
+
+        # No existing active stream, attempt to assign a new one
+        has_streams_but_maxed_out = False
+        has_active_profiles = False
+
+        # Iterate through channel streams and their profiles
+        for stream in self.streams.all().order_by("channelstream__order"):
+            # Retrieve the M3U account associated with the stream.
+            m3u_account = stream.m3u_account
+            if not m3u_account:
+                logger.debug(f"Stream {stream.id} has no M3U account")
+                continue
+            if m3u_account.is_active == False:
+                logger.debug(f"M3U account {m3u_account.id} is inactive, skipping.")
+                continue
+
+            m3u_profiles = m3u_account.profiles.filter(is_active=True)
+            default_profile = next(
+                (obj for obj in m3u_profiles if obj.is_default), None
+            )
+
+            if not default_profile:
+                logger.debug(f"M3U account {m3u_account.id} has no active default profile")
+                continue
+
+            profiles = [default_profile] + [
+                obj for obj in m3u_profiles if not obj.is_default
+            ]
+
+            for profile in profiles:
+                has_active_profiles = True
+
+                # Atomically check and reserve a slot (INCR-first pattern)
+                reserved, current_count = self._check_and_reserve_profile_slot(
+                    profile, redis_client
+                )
+
+                if reserved:
+                    # Slot reserved — assign stream to this channel
+                    redis_client.set(f"channel_stream:{self.id}", stream.id)
+                    redis_client.set(f"stream_profile:{stream.id}", profile.id)
+
+                    return (
+                        stream.id,
+                        profile.id,
+                        None,
+                    )  # Return newly assigned stream and matched profile
+                else:
+                    # At capacity: try to preempt a lower-impact channel on this profile
+                    victim_channel_id = self._pick_channel_to_preempt(
+                        profile_id=profile.id,
+                        requester_level=requester.user_level if requester else 100,
+                        redis_client=redis_client,
+                        exclude_channel_ids=None,
+                    )
+                    if victim_channel_id:
+                        logger.info(f"Preempting channel {victim_channel_id} for new stream on profile {profile.id}")
+                        # return self.id, profile.id, victim_channel_id
+
+                    # This profile is at max connections
+                    has_streams_but_maxed_out = True
+                    logger.debug(
+                        f"Profile {profile.id} at max connections: "
+                        f"{current_count}/{profile.max_streams}"
+                    )
+
+        # No available streams - determine specific reason
+        if has_streams_but_maxed_out:
+            error_reason = "All active M3U profiles have reached maximum connection limits"
+        elif has_active_profiles:
+            error_reason = "No compatible active profile found for any assigned stream"
+        else:
+            error_reason = "No active profiles found for any assigned stream"
+
+        return None, None, error_reason
+
+    def release_stream(self):
+        """
+        Called when a stream is finished to release the lock.
+
+        Returns:
+            bool: True if stream was successfully released, False if
+                  no stream/profile info could be found for cleanup.
+        """
+        redis_client = RedisClient.get_client()
+
+        stream_id = redis_client.get(f"channel_stream:{self.id}")
+        if not stream_id:
+            # Primary key missing — try metadata hash fallback.
+            # The proxy may have already cleaned up channel_stream/stream_profile
+            # keys, but the metadata hash can still have the stream_id and profile.
+            metadata_key = RedisKeys.channel_metadata(str(self.uuid))
+            meta_stream_id = redis_client.hget(
+                metadata_key, ChannelMetadataField.STREAM_ID
+            )
+            meta_profile_id = redis_client.hget(
+                metadata_key, ChannelMetadataField.M3U_PROFILE
+            )
+
+            if meta_stream_id and meta_profile_id:
+                stream_id = int(meta_stream_id)
+                profile_id = int(meta_profile_id)
+                logger.debug(
+                    f"Channel {self.uuid}: recovered stream_id={stream_id}, "
+                    f"profile_id={profile_id} from metadata fallback"
+                )
+                # Clean up any remaining keys
+                redis_client.delete(f"channel_stream:{self.id}")
+                redis_client.delete(f"stream_profile:{stream_id}")
+
+                # Clear metadata fields so duplicate release_stream() calls
+                # won't find them and DECR again
+                redis_client.hdel(
+                    metadata_key,
+                    ChannelMetadataField.STREAM_ID,
+                    ChannelMetadataField.M3U_PROFILE,
+                )
+
+                profile_connections_key = f"profile_connections:{profile_id}"
+                current_count = int(
+                    redis_client.get(profile_connections_key) or 0
+                )
+                if current_count > 0:
+                    redis_client.decr(profile_connections_key)
+                return True
+
+            logger.debug(
+                f"Channel {self.uuid}: no stream info found in primary keys "
+                f"or metadata fallback"
+            )
+            return False
+
+        redis_client.delete(f"channel_stream:{self.id}")  # Remove active stream
+
+        stream_id = int(stream_id)
+        logger.debug(
+            f"Channel {self.uuid}: found stream_id={stream_id} for "
+            f"channel_stream:{self.id}"
+        )
+
+        # Get the matched profile for cleanup
+        profile_id = redis_client.get(f"stream_profile:{stream_id}")
+        if profile_id:
+            redis_client.delete(f"stream_profile:{stream_id}")  # Remove profile association
+            profile_id = int(profile_id)
+        else:
+            # stream_profile key missing — try metadata hash fallback
+            metadata_key = RedisKeys.channel_metadata(str(self.uuid))
+            meta_profile_id = redis_client.hget(
+                metadata_key, ChannelMetadataField.M3U_PROFILE
+            )
+            if meta_profile_id:
+                profile_id = int(meta_profile_id)
+                logger.debug(
+                    f"Channel {self.uuid}: recovered profile_id={profile_id} "
+                    f"from metadata fallback (stream_profile:{stream_id} was missing)"
+                )
+            else:
+                logger.warning(
+                    f"Channel {self.uuid}: no profile found for "
+                    f"stream_profile:{stream_id} or in metadata fallback"
+                )
+                return False
+        logger.debug(
+            f"Channel {self.uuid}: found profile_id={profile_id} for "
+            f"stream {stream_id}"
+        )
+
+        profile_connections_key = f"profile_connections:{profile_id}"
+
+        # Only decrement if the profile had a max_connections limit
+        current_count = int(redis_client.get(profile_connections_key) or 0)
+        if current_count > 0:
+            redis_client.decr(profile_connections_key)
+
+        # Clear metadata fields so duplicate release_stream() calls
+        # (e.g. from _clean_redis_keys or ChannelService.stop_channel)
+        # won't find them via fallback and DECR again
+        metadata_key = RedisKeys.channel_metadata(str(self.uuid))
+        redis_client.hdel(
+            metadata_key,
+            ChannelMetadataField.STREAM_ID,
+            ChannelMetadataField.M3U_PROFILE,
+        )
+
+        return True
+
+    def update_stream_profile(self, new_profile_id):
+        """
+        Updates the profile for the current stream and adjusts connection counts.
+
+        Args:
+            new_profile_id: The ID of the new stream profile to use
+
+        Returns:
+            bool: True if successful, False otherwise
+        """
+        redis_client = RedisClient.get_client()
+
+        # Get current stream ID
+        stream_id_bytes = redis_client.get(f"channel_stream:{self.id}")
+        if not stream_id_bytes:
+            logger.debug("No active stream found for channel")
+            return False
+
+        stream_id = int(stream_id_bytes)
+
+        # Get current profile ID
+        current_profile_id_bytes = redis_client.get(f"stream_profile:{stream_id}")
+        if not current_profile_id_bytes:
+            logger.debug("No profile found for current stream")
+            return False
+
+        current_profile_id = int(current_profile_id_bytes)
+
+        # Don't do anything if the profile is already set to the requested one
+        if current_profile_id == new_profile_id:
+            return True
+
+        # Use pipeline for atomic profile switch to prevent counter drift
+        # if an exception occurs between DECR and INCR
+        old_profile_connections_key = f"profile_connections:{current_profile_id}"
+        new_profile_connections_key = f"profile_connections:{new_profile_id}"
+        old_count = int(redis_client.get(old_profile_connections_key) or 0)
+
+        pipe = redis_client.pipeline()
+        if old_count > 0:
+            pipe.decr(old_profile_connections_key)
+        pipe.set(f"stream_profile:{stream_id}", new_profile_id)
+        pipe.incr(new_profile_connections_key)
+        pipe.execute()
+        logger.info(
+            f"Updated stream {stream_id} profile from {current_profile_id} to {new_profile_id}"
+        )
+        return True
+
+
+class ChannelProfile(models.Model):
+    name = models.CharField(max_length=100, unique=True)
+
+
+class ChannelProfileMembership(models.Model):
+    channel_profile = models.ForeignKey(ChannelProfile, on_delete=models.CASCADE)
+    channel = models.ForeignKey(Channel, on_delete=models.CASCADE)
+    enabled = models.BooleanField(
+        default=True
+    )  # Track if the channel is enabled for this group
+
+    class Meta:
+        unique_together = ("channel_profile", "channel")
+
+
+class ChannelStream(models.Model):
+    channel = models.ForeignKey(Channel, on_delete=models.CASCADE)
+    stream = models.ForeignKey(Stream, on_delete=models.CASCADE)
+    order = models.PositiveIntegerField(default=0)  # Ordering field
+
+    class Meta:
+        ordering = ["order"]  # Ensure streams are retrieved in order
+        constraints = [
+            models.UniqueConstraint(
+                fields=["channel", "stream"], name="unique_channel_stream"
+            )
+        ]
+
+
+class ChannelGroupM3UAccount(models.Model):
+    channel_group = models.ForeignKey(
+        ChannelGroup, on_delete=models.CASCADE, related_name="m3u_accounts"
+    )
+    m3u_account = models.ForeignKey(
+        M3UAccount, on_delete=models.CASCADE, related_name="channel_group"
+    )
+    custom_properties = models.JSONField(default=dict, blank=True, null=True)
+    enabled = models.BooleanField(default=True)
+    auto_channel_sync = models.BooleanField(
+        default=False,
+        help_text='Automatically create/delete channels to match streams in this group'
+    )
+    auto_sync_channel_start = models.FloatField(
+        null=True,
+        blank=True,
+        help_text='Starting channel number for auto-created channels in this group'
+    )
+    last_seen = models.DateTimeField(
+        default=timezone.now,
+        db_index=True,
+        help_text='Last time this group was seen in the M3U source during a refresh'
+    )
+    is_stale = models.BooleanField(
+        default=False,
+        db_index=True,
+        help_text='Whether this group relationship is stale (not seen in recent refresh, pending deletion)'
+    )
+
+    class Meta:
+        unique_together = ("channel_group", "m3u_account")
+
+    def __str__(self):
+        return f"{self.channel_group.name} - {self.m3u_account.name} (Enabled: {self.enabled})"
+
+
+class Logo(models.Model):
+    name = models.CharField(max_length=255)
+    url = models.TextField(unique=True)
+
+    def __str__(self):
+        return self.name
+
+
+class Recording(models.Model):
+    channel = models.ForeignKey(
+        "Channel", on_delete=models.CASCADE, related_name="recordings"
+    )
+    start_time = models.DateTimeField()
+    end_time = models.DateTimeField()
+    task_id = models.CharField(max_length=255, null=True, blank=True)
+    custom_properties = models.JSONField(default=dict, blank=True, null=True)
+
+    def __str__(self):
+        return f"{self.channel.name} - {self.start_time} to {self.end_time}"
+
+
+class RecurringRecordingRule(models.Model):
+    """Rule describing a recurring manual DVR schedule."""
+
+    channel = models.ForeignKey(
+        "Channel",
+        on_delete=models.CASCADE,
+        related_name="recurring_rules",
+    )
+    days_of_week = models.JSONField(default=list)
+    start_time = models.TimeField()
+    end_time = models.TimeField()
+    enabled = models.BooleanField(default=True)
+    name = models.CharField(max_length=255, blank=True)
+    start_date = models.DateField(null=True, blank=True)
+    end_date = models.DateField(null=True, blank=True)
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+
+    class Meta:
+        ordering = ["channel", "start_time"]
+
+    def __str__(self):
+        channel_name = getattr(self.channel, "name", str(self.channel_id))
+        return f"Recurring rule for {channel_name}"
+
+    def cleaned_days(self):
+        try:
+            return sorted({int(d) for d in (self.days_of_week or []) if 0 <= int(d) <= 6})
+        except Exception:
+            return []

apps/channels/serializers.py

@@ -0,0 +1,537 @@
+import json
+from datetime import datetime
+
+from rest_framework import serializers
+from .models import (
+    Stream,
+    Channel,
+    ChannelGroup,
+    ChannelStream,
+    ChannelGroupM3UAccount,
+    Logo,
+    ChannelProfile,
+    ChannelProfileMembership,
+    Recording,
+    RecurringRecordingRule,
+)
+from apps.epg.serializers import EPGDataSerializer
+from core.models import StreamProfile
+from apps.epg.models import EPGData
+from django.urls import reverse
+from rest_framework import serializers
+from django.utils import timezone
+from core.utils import validate_flexible_url
+
+
+class LogoSerializer(serializers.ModelSerializer):
+    cache_url = serializers.SerializerMethodField()
+    channel_count = serializers.SerializerMethodField()
+    is_used = serializers.SerializerMethodField()
+    channel_names = serializers.SerializerMethodField()
+
+    class Meta:
+        model = Logo
+        fields = ["id", "name", "url", "cache_url", "channel_count", "is_used", "channel_names"]
+
+    def validate_url(self, value):
+        """Validate that the URL is unique for creation or update"""
+        if self.instance and self.instance.url == value:
+            return value
+
+        if Logo.objects.filter(url=value).exists():
+            raise serializers.ValidationError("A logo with this URL already exists.")
+
+        return value
+
+    def create(self, validated_data):
+        """Handle logo creation with proper URL validation"""
+        return Logo.objects.create(**validated_data)
+
+    def update(self, instance, validated_data):
+        """Handle logo updates"""
+        for attr, value in validated_data.items():
+            setattr(instance, attr, value)
+        instance.save()
+        return instance
+
+    def get_cache_url(self, obj):
+        # return f"/api/channels/logos/{obj.id}/cache/"
+        request = self.context.get("request")
+        if request:
+            return request.build_absolute_uri(
+                reverse("api:channels:logo-cache", args=[obj.id])
+            )
+        return reverse("api:channels:logo-cache", args=[obj.id])
+
+    def get_channel_count(self, obj):
+        """Get the number of channels using this logo"""
+        return obj.channels.count()
+
+    def get_is_used(self, obj):
+        """Check if this logo is used by any channels"""
+        return obj.channels.exists()
+
+    def get_channel_names(self, obj):
+        """Get the names of channels using this logo (limited to first 5)"""
+        names = []
+
+        # Get channel names
+        channels = obj.channels.all()[:5]
+        for channel in channels:
+            names.append(f"Channel: {channel.name}")
+
+        # Calculate total count for "more" message
+        total_count = self.get_channel_count(obj)
+        if total_count > 5:
+            names.append(f"...and {total_count - 5} more")
+
+        return names
+
+
+#
+# Stream
+#
+class StreamSerializer(serializers.ModelSerializer):
+    url = serializers.CharField(
+        required=False,
+        allow_blank=True,
+        allow_null=True,
+        validators=[validate_flexible_url]
+    )
+    stream_profile_id = serializers.PrimaryKeyRelatedField(
+        queryset=StreamProfile.objects.all(),
+        source="stream_profile",
+        allow_null=True,
+        required=False,
+    )
+    read_only_fields = ["is_custom", "m3u_account", "stream_hash", "stream_id", "stream_chno"]
+
+    class Meta:
+        model = Stream
+        fields = [
+            "id",
+            "name",
+            "url",
+            "m3u_account",  # Uncomment if using M3U fields
+            "logo_url",
+            "tvg_id",
+            "local_file",
+            "current_viewers",
+            "updated_at",
+            "last_seen",
+            "is_stale",
+            "is_adult",
+            "stream_profile_id",
+            "is_custom",
+            "channel_group",
+            "stream_hash",
+            "stream_stats",
+            "stream_stats_updated_at",
+            "stream_id",
+            "stream_chno",
+        ]
+
+    def get_fields(self):
+        fields = super().get_fields()
+
+        # Unable to edit specific properties if this stream was created from an M3U account
+        if (
+            self.instance
+            and getattr(self.instance, "m3u_account", None)
+            and not self.instance.is_custom
+        ):
+            fields["id"].read_only = True
+            fields["name"].read_only = True
+            fields["url"].read_only = True
+            fields["m3u_account"].read_only = True
+            fields["tvg_id"].read_only = True
+            fields["channel_group"].read_only = True
+
+        return fields
+
+
+class ChannelGroupM3UAccountSerializer(serializers.ModelSerializer):
+    m3u_accounts = serializers.IntegerField(source="m3u_accounts.id", read_only=True)
+    enabled = serializers.BooleanField()
+    auto_channel_sync = serializers.BooleanField(default=False)
+    auto_sync_channel_start = serializers.FloatField(allow_null=True, required=False)
+    custom_properties = serializers.JSONField(required=False)
+
+    class Meta:
+        model = ChannelGroupM3UAccount
+        fields = ["m3u_accounts", "channel_group", "enabled", "auto_channel_sync", "auto_sync_channel_start", "custom_properties", "is_stale", "last_seen"]
+
+    def to_representation(self, instance):
+        data = super().to_representation(instance)
+
+        custom_props = instance.custom_properties or {}
+
+        return data
+
+    def to_internal_value(self, data):
+        # Accept both dict and JSON string for custom_properties (for backward compatibility)
+        val = data.get("custom_properties")
+        if isinstance(val, str):
+            try:
+                data["custom_properties"] = json.loads(val)
+            except Exception:
+                pass
+
+        return super().to_internal_value(data)
+
+#
+# Channel Group
+#
+class ChannelGroupSerializer(serializers.ModelSerializer):
+    channel_count = serializers.SerializerMethodField()
+    m3u_account_count = serializers.SerializerMethodField()
+    m3u_accounts = ChannelGroupM3UAccountSerializer(
+        many=True,
+        read_only=True
+    )
+
+    class Meta:
+        model = ChannelGroup
+        fields = ["id", "name", "channel_count", "m3u_account_count", "m3u_accounts"]
+
+    def get_channel_count(self, obj):
+        """Get count of channels in this group"""
+        return obj.channels.count()
+
+    def get_m3u_account_count(self, obj):
+        """Get count of M3U accounts associated with this group"""
+        return obj.m3u_accounts.count()
+
+
+class ChannelProfileSerializer(serializers.ModelSerializer):
+    channels = serializers.SerializerMethodField()
+
+    class Meta:
+        model = ChannelProfile
+        fields = ["id", "name", "channels"]
+
+    def get_channels(self, obj):
+        memberships = ChannelProfileMembership.objects.filter(
+            channel_profile=obj, enabled=True
+        )
+        return [membership.channel.id for membership in memberships]
+
+
+class ChannelProfileMembershipSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = ChannelProfileMembership
+        fields = ["channel", "enabled"]
+
+
+class ChanneProfilelMembershipUpdateSerializer(serializers.Serializer):
+    channel_id = serializers.IntegerField()  # Ensure channel_id is an integer
+    enabled = serializers.BooleanField()
+
+
+class BulkChannelProfileMembershipSerializer(serializers.Serializer):
+    channels = serializers.ListField(
+        child=ChanneProfilelMembershipUpdateSerializer(),  # Use the nested serializer
+        allow_empty=False,
+    )
+
+    def validate_channels(self, value):
+        if not value:
+            raise serializers.ValidationError("At least one channel must be provided.")
+        return value
+
+
+#
+# Channel
+#
+class ChannelSerializer(serializers.ModelSerializer):
+    # Show nested group data, or ID
+    # Ensure channel_number is explicitly typed as FloatField and properly validated
+    channel_number = serializers.FloatField(
+        allow_null=True,
+        required=False,
+        error_messages={"invalid": "Channel number must be a valid decimal number."},
+    )
+    channel_group_id = serializers.PrimaryKeyRelatedField(
+        queryset=ChannelGroup.objects.all(), source="channel_group", required=False
+    )
+    epg_data_id = serializers.PrimaryKeyRelatedField(
+        queryset=EPGData.objects.all(),
+        source="epg_data",
+        required=False,
+        allow_null=True,
+    )
+
+    stream_profile_id = serializers.PrimaryKeyRelatedField(
+        queryset=StreamProfile.objects.all(),
+        source="stream_profile",
+        allow_null=True,
+        required=False,
+    )
+
+    streams = serializers.PrimaryKeyRelatedField(
+        queryset=Stream.objects.all(), many=True, required=False
+    )
+
+    logo_id = serializers.PrimaryKeyRelatedField(
+        queryset=Logo.objects.all(),
+        source="logo",
+        allow_null=True,
+        required=False,
+    )
+
+    auto_created_by_name = serializers.SerializerMethodField()
+
+    class Meta:
+        model = Channel
+        fields = [
+            "id",
+            "channel_number",
+            "name",
+            "channel_group_id",
+            "tvg_id",
+            "tvc_guide_stationid",
+            "epg_data_id",
+            "streams",
+            "stream_profile_id",
+            "uuid",
+            "logo_id",
+            "user_level",
+            "is_adult",
+            "auto_created",
+            "auto_created_by",
+            "auto_created_by_name",
+        ]
+
+    def to_representation(self, instance):
+        include_streams = self.context.get("include_streams", False)
+
+        if include_streams:
+            self.fields["streams"] = serializers.SerializerMethodField()
+            return super().to_representation(instance)
+        else:
+            # Fix: For PATCH/PUT responses, ensure streams are ordered
+            representation = super().to_representation(instance)
+            if "streams" in representation:
+                representation["streams"] = list(
+                    instance.streams.all()
+                    .order_by("channelstream__order")
+                    .values_list("id", flat=True)
+                )
+            return representation
+
+    def get_logo(self, obj):
+        return LogoSerializer(obj.logo).data
+
+    def get_streams(self, obj):
+        """Retrieve ordered stream IDs for GET requests."""
+        return StreamSerializer(
+            obj.streams.all().order_by("channelstream__order"), many=True
+        ).data
+
+    def create(self, validated_data):
+        streams = validated_data.pop("streams", [])
+        channel_number = validated_data.pop(
+            "channel_number", Channel.get_next_available_channel_number()
+        )
+        validated_data["channel_number"] = channel_number
+
+        # Auto-assign Default Group if no channel_group is specified
+        if "channel_group" not in validated_data or validated_data.get("channel_group") is None:
+            from apps.channels.models import ChannelGroup
+            default_group, _ = ChannelGroup.objects.get_or_create(name="Default Group")
+            validated_data["channel_group"] = default_group
+
+        channel = Channel.objects.create(**validated_data)
+
+        # Add streams in the specified order
+        for index, stream in enumerate(streams):
+            ChannelStream.objects.create(
+                channel=channel, stream_id=stream.id, order=index
+            )
+
+        return channel
+
+    def update(self, instance, validated_data):
+        streams = validated_data.pop("streams", None)
+
+        # Update standard fields
+        for attr, value in validated_data.items():
+            setattr(instance, attr, value)
+
+        instance.save()
+
+        if streams is not None:
+            # Normalize stream IDs
+            normalized_ids = [
+                stream.id if hasattr(stream, "id") else stream for stream in streams
+            ]
+            print(normalized_ids)
+
+            # Get current mapping of stream_id -> ChannelStream
+            current_links = {
+                cs.stream_id: cs for cs in instance.channelstream_set.all()
+            }
+
+            # Track existing stream IDs
+            existing_ids = set(current_links.keys())
+            new_ids = set(normalized_ids)
+
+            # Delete any links not in the new list
+            to_remove = existing_ids - new_ids
+            if to_remove:
+                instance.channelstream_set.filter(stream_id__in=to_remove).delete()
+
+            # Update or create with new order
+            for order, stream_id in enumerate(normalized_ids):
+                if stream_id in current_links:
+                    cs = current_links[stream_id]
+                    if cs.order != order:
+                        cs.order = order
+                        cs.save(update_fields=["order"])
+                else:
+                    ChannelStream.objects.create(
+                        channel=instance, stream_id=stream_id, order=order
+                    )
+
+        return instance
+
+    def validate_channel_number(self, value):
+        """Ensure channel_number is properly processed as a float"""
+        if value is None:
+            return value
+
+        try:
+            # Ensure it's processed as a float
+            return float(value)
+        except (ValueError, TypeError):
+            raise serializers.ValidationError(
+                "Channel number must be a valid decimal number."
+            )
+
+    def validate_stream_profile(self, value):
+        """Handle special case where empty/0 values mean 'use default' (null)"""
+        if value == "0" or value == 0 or value == "" or value is None:
+            return None
+        return value  # PrimaryKeyRelatedField will handle the conversion to object
+
+    def get_auto_created_by_name(self, obj):
+        """Get the name of the M3U account that auto-created this channel."""
+        if obj.auto_created_by:
+            return obj.auto_created_by.name
+        return None
+
+
+class RecordingSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = Recording
+        fields = "__all__"
+        read_only_fields = ["task_id"]
+
+    def validate(self, data):
+        from core.models import CoreSettings
+        start_time = data.get("start_time")
+        end_time = data.get("end_time")
+
+        if start_time and timezone.is_naive(start_time):
+            start_time = timezone.make_aware(start_time, timezone.get_current_timezone())
+            data["start_time"] = start_time
+        if end_time and timezone.is_naive(end_time):
+            end_time = timezone.make_aware(end_time, timezone.get_current_timezone())
+            data["end_time"] = end_time
+
+        # If this is an EPG-based recording (program provided), apply global pre/post offsets
+        try:
+            cp = data.get("custom_properties") or {}
+            is_epg_based = isinstance(cp, dict) and isinstance(cp.get("program"), (dict,))
+        except Exception:
+            is_epg_based = False
+
+        if is_epg_based and start_time and end_time:
+            try:
+                pre_min = int(CoreSettings.get_dvr_pre_offset_minutes())
+            except Exception:
+                pre_min = 0
+            try:
+                post_min = int(CoreSettings.get_dvr_post_offset_minutes())
+            except Exception:
+                post_min = 0
+            from datetime import timedelta
+            try:
+                if pre_min and pre_min > 0:
+                    start_time = start_time - timedelta(minutes=pre_min)
+            except Exception:
+                pass
+            try:
+                if post_min and post_min > 0:
+                    end_time = end_time + timedelta(minutes=post_min)
+            except Exception:
+                pass
+            # write back adjusted times so scheduling uses them
+            data["start_time"] = start_time
+            data["end_time"] = end_time
+
+        now = timezone.now()  # timezone-aware current time
+
+        if end_time < now:
+            raise serializers.ValidationError("End time must be in the future.")
+
+        if start_time < now:
+            # Optional: Adjust start_time if it's in the past but end_time is in the future
+            data["start_time"] = now  # or: timezone.now() + timedelta(seconds=1)
+        if end_time <= data["start_time"]:
+            raise serializers.ValidationError("End time must be after start time.")
+
+        return data
+
+
+class RecurringRecordingRuleSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = RecurringRecordingRule
+        fields = "__all__"
+        read_only_fields = ["created_at", "updated_at"]
+
+    def validate_days_of_week(self, value):
+        if not value:
+            raise serializers.ValidationError("Select at least one day of the week")
+        cleaned = []
+        for entry in value:
+            try:
+                iv = int(entry)
+            except (TypeError, ValueError):
+                raise serializers.ValidationError("Days of week must be integers 0-6")
+            if iv < 0 or iv > 6:
+                raise serializers.ValidationError("Days of week must be between 0 (Monday) and 6 (Sunday)")
+            cleaned.append(iv)
+        return sorted(set(cleaned))
+
+    def validate(self, attrs):
+        start = attrs.get("start_time") or getattr(self.instance, "start_time", None)
+        end = attrs.get("end_time") or getattr(self.instance, "end_time", None)
+        start_date = attrs.get("start_date") if "start_date" in attrs else getattr(self.instance, "start_date", None)
+        end_date = attrs.get("end_date") if "end_date" in attrs else getattr(self.instance, "end_date", None)
+        if start_date is None:
+            existing_start = getattr(self.instance, "start_date", None)
+            if existing_start is None:
+                raise serializers.ValidationError("Start date is required")
+        if start_date and end_date and end_date < start_date:
+            raise serializers.ValidationError("End date must be on or after start date")
+        if end_date is None:
+            existing_end = getattr(self.instance, "end_date", None)
+            if existing_end is None:
+                raise serializers.ValidationError("End date is required")
+        if start and end and start_date and end_date:
+            start_dt = datetime.combine(start_date, start)
+            end_dt = datetime.combine(end_date, end)
+            if end_dt <= start_dt:
+                raise serializers.ValidationError("End datetime must be after start datetime")
+        elif start and end and end == start:
+            raise serializers.ValidationError("End time must be different from start time")
+        # Normalize empty strings to None for dates
+        if attrs.get("end_date") == "":
+            attrs["end_date"] = None
+        if attrs.get("start_date") == "":
+            attrs["start_date"] = None
+        return super().validate(attrs)
+
+    def create(self, validated_data):
+        return super().create(validated_data)

apps/channels/signals.py

@@ -0,0 +1,236 @@
+# apps/channels/signals.py
+
+from django.db.models.signals import m2m_changed, pre_save, post_save, post_delete
+from django.dispatch import receiver
+from django.utils.timezone import now, is_aware, make_aware
+from celery.result import AsyncResult
+from django_celery_beat.models import ClockedSchedule, PeriodicTask
+from .models import Channel, Stream, ChannelProfile, ChannelProfileMembership, Recording
+from apps.m3u.models import M3UAccount
+from apps.epg.tasks import parse_programs_for_tvg_id
+import json
+import logging
+from .tasks import run_recording, prefetch_recording_artwork
+from datetime import timedelta
+
+logger = logging.getLogger(__name__)
+
+@receiver(m2m_changed, sender=Channel.streams.through)
+def update_channel_tvg_id_and_logo(sender, instance, action, reverse, model, pk_set, **kwargs):
+    """
+    Whenever streams are added to a channel:
+      1) If the channel doesn't have a tvg_id, fill it from the first newly-added stream that has one.
+    """
+    # We only care about post_add, i.e. once the new streams are fully associated
+    if action == "post_add":
+        # --- 1) Populate channel.tvg_id if empty ---
+        if not instance.tvg_id:
+            # Look for newly added streams that have a nonempty tvg_id
+            streams_with_tvg = model.objects.filter(pk__in=pk_set).exclude(tvg_id__exact='')
+            if streams_with_tvg.exists():
+                instance.tvg_id = streams_with_tvg.first().tvg_id
+                instance.save(update_fields=['tvg_id'])
+
+@receiver(pre_save, sender=Stream)
+def set_default_m3u_account(sender, instance, **kwargs):
+    """
+    This function will be triggered before saving a Stream instance.
+    It sets the default m3u_account if not provided.
+    """
+    if not instance.m3u_account:
+        instance.is_custom = True
+        default_account = M3UAccount.get_custom_account()
+
+        if default_account:
+            instance.m3u_account = default_account
+        else:
+            raise ValueError("No default M3UAccount found.")
+
+@receiver(post_save, sender=Stream)
+def generate_custom_stream_hash(sender, instance, created, **kwargs):
+    """
+    Generate a stable stream_hash for custom streams after creation.
+    Uses the stream's ID to ensure the hash never changes even if name/url is edited.
+    """
+    if instance.is_custom and not instance.stream_hash and created:
+        import hashlib
+        # Use stream ID for a stable, unique hash that never changes
+        unique_string = f"custom_stream_{instance.id}"
+        instance.stream_hash = hashlib.sha256(unique_string.encode()).hexdigest()
+        # Use update to avoid triggering signals again
+        Stream.objects.filter(id=instance.id).update(stream_hash=instance.stream_hash)
+
+@receiver(post_save, sender=Channel)
+def refresh_epg_programs(sender, instance, created, **kwargs):
+    """
+    When a channel is saved, check if the EPG data has changed.
+    If so, trigger a refresh of the program data for the EPG.
+    """
+    # Check if this is an update (not a new channel) and the epg_data has changed
+    if not created and kwargs.get('update_fields') and 'epg_data' in kwargs['update_fields']:
+        logger.info(f"Channel {instance.id} ({instance.name}) EPG data updated, refreshing program data")
+        if instance.epg_data:
+            logger.info(f"Triggering EPG program refresh for {instance.epg_data.tvg_id}")
+            parse_programs_for_tvg_id.delay(instance.epg_data.id)
+    # For new channels with EPG data, also refresh
+    elif created and instance.epg_data:
+        logger.info(f"New channel {instance.id} ({instance.name}) created with EPG data, refreshing program data")
+        parse_programs_for_tvg_id.delay(instance.epg_data.id)
+
+@receiver(post_save, sender=ChannelProfile)
+def create_profile_memberships(sender, instance, created, **kwargs):
+    if created:
+        channels = Channel.objects.all()
+        ChannelProfileMembership.objects.bulk_create([
+            ChannelProfileMembership(channel_profile=instance, channel=channel)
+            for channel in channels
+        ])
+
+def _dvr_task_name(recording_id):
+    """Predictable PeriodicTask name for a DVR recording."""
+    return f"dvr-recording-{recording_id}"
+
+
+def schedule_recording_task(instance, eta=None):
+    """Schedule a recording task via ClockedSchedule + one-off PeriodicTask.
+
+    The task is stored in the database and dispatched by Celery Beat at the
+    scheduled time with no countdown.  This avoids the Redis visibility_timeout
+    redelivery bug that caused duplicate recordings when using apply_async
+    with long countdowns.
+    """
+    if eta is None:
+        eta = instance.start_time
+    if eta is not None and not is_aware(eta):
+        eta = make_aware(eta)
+    # Clamp to now so Beat dispatches immediately for past/current start times
+    if eta <= now():
+        eta = now()
+
+    task_args = [
+        instance.id,
+        instance.channel_id,
+        str(instance.start_time),
+        str(instance.end_time),
+    ]
+
+    clocked, _ = ClockedSchedule.objects.get_or_create(clocked_time=eta)
+    task_name = _dvr_task_name(instance.id)
+    PeriodicTask.objects.update_or_create(
+        name=task_name,
+        defaults={
+            "task": "apps.channels.tasks.run_recording",
+            "clocked": clocked,
+            "args": json.dumps(task_args),
+            "one_off": True,
+            "enabled": True,
+            "interval": None,
+            "crontab": None,
+            "solar": None,
+        },
+    )
+    return task_name
+
+
+def revoke_task(task_id):
+    """Cancel a pending recording task.
+
+    task_id is normally a PeriodicTask name (e.g. "dvr-recording-42").
+    For backwards compatibility with legacy Celery async-result UUIDs,
+    falls back to AsyncResult.revoke().
+    """
+    if not task_id:
+        return
+    # Primary path: delete the PeriodicTask and clean up its ClockedSchedule
+    try:
+        pt = PeriodicTask.objects.get(name=task_id)
+        old_clocked = pt.clocked
+        pt.delete()
+        if old_clocked and not PeriodicTask.objects.filter(clocked=old_clocked).exists():
+            old_clocked.delete()
+        return
+    except PeriodicTask.DoesNotExist:
+        pass
+    # Fallback for legacy Celery task UUIDs
+    try:
+        AsyncResult(task_id).revoke()
+    except Exception:
+        pass
+
+@receiver(pre_save, sender=Recording)
+def revoke_old_task_on_update(sender, instance, **kwargs):
+    if not instance.pk:
+        return  # New instance
+    try:
+        old = Recording.objects.get(pk=instance.pk)
+        if old.task_id and (
+            old.start_time != instance.start_time or
+            old.end_time != instance.end_time or
+            old.channel_id != instance.channel_id
+        ):
+            # Do NOT revoke while the recording is actively streaming.
+            # run_recording re-reads end_time from the DB every ~2 s and extends
+            # its internal deadline dynamically — revoking here would kill the task.
+            old_status = (old.custom_properties or {}).get("status", "")
+            if old_status == "recording":
+                return
+            revoke_task(old.task_id)
+            instance.task_id = None
+    except Recording.DoesNotExist:
+        pass
+
+@receiver(post_save, sender=Recording)
+def schedule_task_on_save(sender, instance, created, **kwargs):
+    try:
+        # Skip processing for internal field-only saves (metadata updates,
+        # task_id assignment, end_time extensions) to prevent re-entrant
+        # artwork dispatch and redundant recording_updated WS events.
+        update_fields = kwargs.get('update_fields')
+        if not created and update_fields is not None and set(update_fields) <= {'custom_properties', 'task_id', 'end_time'}:
+            return
+
+        if not instance.task_id:
+            start_time = instance.start_time
+            end_time = instance.end_time
+
+            # Make datetimes aware (in UTC)
+            if not is_aware(start_time):
+                start_time = make_aware(start_time)
+            if end_time and not is_aware(end_time):
+                end_time = make_aware(end_time)
+
+            current_time = now()
+
+            if start_time > current_time - timedelta(seconds=1):
+                # Future recording — schedule at start_time
+                logger.info(f"Recording {instance.id}: scheduling task at {start_time}")
+                task_id = schedule_recording_task(instance, eta=start_time)
+                instance.task_id = task_id
+                instance.save(update_fields=['task_id'])
+            elif end_time and end_time > current_time:
+                # Currently-playing — start immediately (e.g. series rule for in-progress program)
+                logger.info(f"Recording {instance.id}: start_time in past but end_time still future, scheduling immediately")
+                task_id = schedule_recording_task(instance, eta=current_time)
+                instance.task_id = task_id
+                instance.save(update_fields=['task_id'])
+            else:
+                logger.info(f"Recording {instance.id}: start_time and end_time both in past, not scheduling")
+        # Kick off poster/artwork prefetch to enrich Upcoming cards.
+        # Skip when the recording is already active or finished — run_recording
+        # handles its own poster resolution, and scheduling artwork prefetch
+        # while the task is running causes a race that can overwrite status.
+        cp = instance.custom_properties or {}
+        rec_status = cp.get("status", "")
+        if rec_status not in ("recording", "completed", "stopped", "interrupted"):
+            try:
+                prefetch_recording_artwork.apply_async(args=[instance.id], countdown=1)
+            except Exception as e:
+                print("Error scheduling artwork prefetch:", e)
+    except Exception as e:
+        import traceback
+        print("Error in post_save signal:", e)
+        traceback.print_exc()
+
+@receiver(post_delete, sender=Recording)
+def revoke_task_on_delete(sender, instance, **kwargs):
+    revoke_task(instance.task_id)

apps/channels/tests/test_channel_api.py

@@ -0,0 +1,211 @@
+from django.test import TestCase
+from django.contrib.auth import get_user_model
+from rest_framework.test import APIClient
+from rest_framework import status
+
+from apps.channels.models import Channel, ChannelGroup
+
+User = get_user_model()
+
+
+class ChannelBulkEditAPITests(TestCase):
+    def setUp(self):
+        # Create a test admin user (user_level >= 10) and authenticate
+        self.user = User.objects.create_user(username="testuser", password="testpass123")
+        self.user.user_level = 10  # Set admin level
+        self.user.save()
+        self.client = APIClient()
+        self.client.force_authenticate(user=self.user)
+        self.bulk_edit_url = "/api/channels/channels/edit/bulk/"
+
+        # Create test channel group
+        self.group1 = ChannelGroup.objects.create(name="Test Group 1")
+        self.group2 = ChannelGroup.objects.create(name="Test Group 2")
+
+        # Create test channels
+        self.channel1 = Channel.objects.create(
+            channel_number=1.0,
+            name="Channel 1",
+            tvg_id="channel1",
+            channel_group=self.group1
+        )
+        self.channel2 = Channel.objects.create(
+            channel_number=2.0,
+            name="Channel 2",
+            tvg_id="channel2",
+            channel_group=self.group1
+        )
+        self.channel3 = Channel.objects.create(
+            channel_number=3.0,
+            name="Channel 3",
+            tvg_id="channel3"
+        )
+
+    def test_bulk_edit_success(self):
+        """Test successful bulk update of multiple channels"""
+        data = [
+            {"id": self.channel1.id, "name": "Updated Channel 1"},
+            {"id": self.channel2.id, "name": "Updated Channel 2", "channel_number": 22.0},
+        ]
+
+        response = self.client.patch(self.bulk_edit_url, data, format="json")
+
+        self.assertEqual(response.status_code, status.HTTP_200_OK)
+        self.assertEqual(response.data["message"], "Successfully updated 2 channels")
+        self.assertEqual(len(response.data["channels"]), 2)
+
+        # Verify database changes
+        self.channel1.refresh_from_db()
+        self.channel2.refresh_from_db()
+        self.assertEqual(self.channel1.name, "Updated Channel 1")
+        self.assertEqual(self.channel2.name, "Updated Channel 2")
+        self.assertEqual(self.channel2.channel_number, 22.0)
+
+    def test_bulk_edit_with_empty_validated_data_first(self):
+        """
+        Test the bug fix: when first channel has empty validated_data.
+        This was causing: ValueError: Field names must be given to bulk_update()
+        """
+        # Create a channel with data that will be "unchanged" (empty validated_data)
+        # We'll send the same data it already has
+        data = [
+            # First channel: no actual changes (this would create empty validated_data)
+            {"id": self.channel1.id},
+            # Second channel: has changes
+            {"id": self.channel2.id, "name": "Updated Channel 2"},
+        ]
+
+        response = self.client.patch(self.bulk_edit_url, data, format="json")
+
+        # Should not crash with ValueError
+        self.assertEqual(response.status_code, status.HTTP_200_OK)
+        self.assertEqual(response.data["message"], "Successfully updated 2 channels")
+
+        # Verify the channel with changes was updated
+        self.channel2.refresh_from_db()
+        self.assertEqual(self.channel2.name, "Updated Channel 2")
+
+    def test_bulk_edit_all_empty_updates(self):
+        """Test when all channels have empty updates (no actual changes)"""
+        data = [
+            {"id": self.channel1.id},
+            {"id": self.channel2.id},
+        ]
+
+        response = self.client.patch(self.bulk_edit_url, data, format="json")
+
+        # Should succeed without calling bulk_update
+        self.assertEqual(response.status_code, status.HTTP_200_OK)
+        self.assertEqual(response.data["message"], "Successfully updated 2 channels")
+
+    def test_bulk_edit_mixed_fields(self):
+        """Test bulk update where different channels update different fields"""
+        data = [
+            {"id": self.channel1.id, "name": "New Name 1"},
+            {"id": self.channel2.id, "channel_number": 99.0},
+            {"id": self.channel3.id, "tvg_id": "new_tvg_id", "name": "New Name 3"},
+        ]
+
+        response = self.client.patch(self.bulk_edit_url, data, format="json")
+
+        self.assertEqual(response.status_code, status.HTTP_200_OK)
+        self.assertEqual(response.data["message"], "Successfully updated 3 channels")
+
+        # Verify all updates
+        self.channel1.refresh_from_db()
+        self.channel2.refresh_from_db()
+        self.channel3.refresh_from_db()
+
+        self.assertEqual(self.channel1.name, "New Name 1")
+        self.assertEqual(self.channel2.channel_number, 99.0)
+        self.assertEqual(self.channel3.tvg_id, "new_tvg_id")
+        self.assertEqual(self.channel3.name, "New Name 3")
+
+    def test_bulk_edit_with_channel_group(self):
+        """Test bulk update with channel_group_id changes"""
+        data = [
+            {"id": self.channel1.id, "channel_group_id": self.group2.id},
+            {"id": self.channel3.id, "channel_group_id": self.group1.id},
+        ]
+
+        response = self.client.patch(self.bulk_edit_url, data, format="json")
+
+        self.assertEqual(response.status_code, status.HTTP_200_OK)
+
+        # Verify group changes
+        self.channel1.refresh_from_db()
+        self.channel3.refresh_from_db()
+        self.assertEqual(self.channel1.channel_group, self.group2)
+        self.assertEqual(self.channel3.channel_group, self.group1)
+
+    def test_bulk_edit_nonexistent_channel(self):
+        """Test bulk update with a channel that doesn't exist"""
+        nonexistent_id = 99999
+        data = [
+            {"id": nonexistent_id, "name": "Should Fail"},
+            {"id": self.channel1.id, "name": "Should Still Update"},
+        ]
+
+        response = self.client.patch(self.bulk_edit_url, data, format="json")
+
+        # Should return 400 with errors
+        self.assertEqual(response.status_code, status.HTTP_400_BAD_REQUEST)
+        self.assertIn("errors", response.data)
+        self.assertEqual(len(response.data["errors"]), 1)
+        self.assertEqual(response.data["errors"][0]["channel_id"], nonexistent_id)
+        self.assertEqual(response.data["errors"][0]["error"], "Channel not found")
+
+        # The valid channel should still be updated
+        self.assertEqual(response.data["updated_count"], 1)
+
+    def test_bulk_edit_validation_error(self):
+        """Test bulk update with invalid data (validation error)"""
+        data = [
+            {"id": self.channel1.id, "channel_number": "invalid_number"},
+        ]
+
+        response = self.client.patch(self.bulk_edit_url, data, format="json")
+
+        # Should return 400 with validation errors
+        self.assertEqual(response.status_code, status.HTTP_400_BAD_REQUEST)
+        self.assertIn("errors", response.data)
+        self.assertEqual(len(response.data["errors"]), 1)
+        self.assertIn("channel_number", response.data["errors"][0]["errors"])
+
+    def test_bulk_edit_empty_channel_updates(self):
+        """Test bulk update with empty list"""
+        data = []
+
+        response = self.client.patch(self.bulk_edit_url, data, format="json")
+
+        # Empty list is accepted and returns success with 0 updates
+        self.assertEqual(response.status_code, status.HTTP_200_OK)
+        self.assertEqual(response.data["message"], "Successfully updated 0 channels")
+
+    def test_bulk_edit_missing_channel_updates(self):
+        """Test bulk update without proper format (dict instead of list)"""
+        data = {"channel_updates": {}}
+
+        response = self.client.patch(self.bulk_edit_url, data, format="json")
+
+        self.assertEqual(response.status_code, status.HTTP_400_BAD_REQUEST)
+        self.assertEqual(response.data["error"], "Expected a list of channel updates")
+
+    def test_bulk_edit_preserves_other_fields(self):
+        """Test that bulk update only changes specified fields"""
+        original_channel_number = self.channel1.channel_number
+        original_tvg_id = self.channel1.tvg_id
+
+        data = [
+            {"id": self.channel1.id, "name": "Only Name Changed"},
+        ]
+
+        response = self.client.patch(self.bulk_edit_url, data, format="json")
+
+        self.assertEqual(response.status_code, status.HTTP_200_OK)
+
+        # Verify only name changed, other fields preserved
+        self.channel1.refresh_from_db()
+        self.assertEqual(self.channel1.name, "Only Name Changed")
+        self.assertEqual(self.channel1.channel_number, original_channel_number)
+        self.assertEqual(self.channel1.tvg_id, original_tvg_id)