A Flask-based web application that runs the Audiodeskription pipeline: VAD pause detection, Whisper transcription, scene image extraction, and GPT-powered audio description generation.

docker build -f webapp/Dockerfile -t audiodeskription-webapp .

docker run \
  -p 5000:5000 \
  -e OPENAI_API_KEY=sk-... \
  -v /my/local/jobs:/app/jobs \
  audiodeskription-webapp

Then open http://localhost:5000.

All Kubernetes manifests live in k8s/ and are managed by Kustomize. Point an ArgoCD Application at that directory — ArgoCD will create every resource (Namespace, ConfigMaps, Secret, PVC, Deployment, Service, Ingress) automatically.

Save this as k8s/argocd-app.yaml (already included) and apply it once into the argocd namespace. It is not part of the Kustomize root so ArgoCD doesn't try to manage itself.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: audiodeskription
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/YOUR_ORG/Audiodeskriptionen_SS25   # ← replace
    targetRevision: main
    path: k8s
  destination:
    server: https://kubernetes.default.svc
    namespace: audiodeskription
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true
      - ServerSideApply=true

# Apply once – ArgoCD takes it from there
kubectl apply -k k8s/argocd/root -n argocd

The recommended setup uses the App of Apps pattern:

If you manage the root ArgoCD Application outside this repository, point it to webapp/k8s/argocd/apps and deploy it into the argocd namespace. The child Applications then deploy staging and release into their own target namespaces.

The app reads OPENAI_API_KEY from a Kubernetes Secret. The overlays include Bitnami SealedSecret manifests. To create or rotate the encrypted values for your cluster:

# Staging: creates Secret openai-secret-staging in audiodeskription-staging
printf '%s' 'sk-...' \
  | kubeseal --raw \
      --name openai-secret-staging \
      --namespace audiodeskription-staging

# Release/prod: creates Secret openai-secret in audiodeskription
printf '%s' 'sk-...' \
  | kubeseal --raw \
      --name openai-secret \
      --namespace audiodeskription

Paste the resulting ciphertext as spec.encryptedData.OPENAI_API_KEY in:

• k8s/overlays/staging/openai-sealedsecret.yaml
• k8s/overlays/release/openai-sealedsecret.yaml

Keep the names and namespaces unchanged; SealedSecrets are namespace/name bound unless you deliberately use a different sealing scope.

CNPG bootstrap credentials are managed as SealedSecrets in overlays:

• k8s/overlays/release/cnpg-sealedsecret.yaml
• k8s/overlays/staging/cnpg-sealedsecret.yaml

Generate fresh random passwords and ciphertexts with:

./k8s/scripts/generate-cnpg-sealed-secrets.sh release
./k8s/scripts/generate-cnpg-sealed-secrets.sh staging

The script uses: kubeseal --controller-name sealed-secrets --controller-namespace kube-system by default.

Paste the printed ciphertexts into the matching encryptedData keys.
Do not commit plain Kubernetes Secret manifests with raw passwords.

Edit the relevant ConfigMap file and push to main — ArgoCD syncs within ≈3 minutes and rolls the pod.

# Example: update the AD rules
vim k8s/base/configmap-prompts.yaml
git commit -am "chore: update AD rules"
git push

The app expects a YAML file that defines presets – named configurations for the GPT description step. The file path is set via the GPT_CONFIG_PATH env var (default: /app/config/gpt_config.yaml).

presets:
  <preset-name>:
    model: gpt-4o              # OpenAI model name
    temperature: 0.2           # 0.0 – 2.0
    max_output_tokens: 1024    # Max tokens in the completion
    detail: high               # Image detail level: "low" | "high" | "auto"

All keys inside a preset are optional — missing values fall back to the defaults used by /api/run/gpt.

Mount your own preset file into the container:

docker run \
  -p 5000:5000 \
  -e OPENAI_API_KEY=sk-... \
  -e GPT_CONFIG_PATH=/app/config/gpt_config.yaml \
  -v /path/to/my/gpt_config.yaml:/app/config/gpt_config.yaml:ro \
  audiodeskription-webapp

In K8s, the file is stored as the gpt-config ConfigMap and mounted read-only at /app/config/. To add or update presets, edit k8s/base/configmap-gpt.yaml and push — ArgoCD will sync the change and restart the pod automatically.

The notebook (step 05a) loads the GPT prompts from plain .txt files rather than hard-coding them. The webapp's /api/run/gpt endpoint accepts the same content as request-body strings. Understanding the file structure helps you author prompts that match the notebook's behaviour.

The notebook concatenates the files into two final prompts:

SYSTEM_FINAL  =  system_instruction
              +  "\n\n# Audiodeskription – Regeln\n"  +  ad_rules
              +  "\n\n# Few-Shots / Beispiele\n"      +  few_shots   (only if provided)

USER_BASE     =  user_instruction

SYSTEM_FINAL becomes the OpenAI system message. USER_BASE is sent as the user message together with the slot image(s).

Pass the assembled text directly in the POST body of /api/run/gpt:

{
  "job_id": "<uuid>",
  "system_prompt": "<contents of SYSTEM_FINAL>",
  "user_prompt":   "<contents of USER_BASE>",
  "model": "gpt-4o",
  "temperature": 0.2,
  "max_tokens": 1024,
  "detail": "high"
}

When the GPT_PROMPTS_DIR environment variable is set, the app reads the four files from that directory at request time and assembles SYSTEM_FINAL / USER_BASE automatically. Explicit system_prompt / user_prompt fields in the request body always take precedence.

mkdir -p my_prompts
# put your .txt files in my_prompts/
docker run \
  -p 5000:5000 \
  -e OPENAI_API_KEY=sk-... \
  -e GPT_PROMPTS_DIR=/app/config/prompts \
  -v $(pwd)/my_prompts:/app/config/prompts:ro \
  audiodeskription-webapp

The prompts are stored in k8s/base/configmap-prompts.yaml and mounted read-only at /app/config/prompts/. Edit the file and push — ArgoCD will sync and restart the pod. The GPT_PROMPTS_DIR=/app/config/prompts env var is already set in k8s/base/deployment.yaml.

• Python ≥ 3.11
• uv (pip install uv or curl -Lsf https://astral.sh/uv/install.sh | sh)
• ffmpeg on $PATH (required by moviepy / scenedetect)

cd webapp
uv sync                          # installs all deps from uv.lock

export OPENAI_API_KEY=sk-...
uv run python -m backend.app     # or: flask --app backend.app run --debug

The dev server starts on http://localhost:5000. For local reloads, the backend uses a short graceful-shutdown timeout so open SSE connections do not block code updates for long. Override it if needed:

UVICORN_GRACEFUL_TIMEOUT=5 uv run python -m backend.app

Each uploaded video creates a job directory under $AD_JOBS_DIR/<uuid>/ containing:

<uuid>/
├── <original-filename>.mp4   # uploaded video
├── audio.wav                 # extracted 16 kHz mono audio
├── frames/                   # scene mid-frames (JPEGs)
├── gapfill/                  # extra frames extracted for AD slots
└── output/
    ├── ad_broadcast.srt
    ├── ad_broadcast.json
    ├── ad_directors.srt
    └── ad_directors.json

With AD_DATABASE_URL set, the backend uses PostgreSQL for:

• user config (/api/user/config)
• user-managed AD presets (/api/user/presets)

Run migrations before rollout:

AD_DATABASE_URL=postgresql://... uv run python -m backend.db.migrate

Kubernetes CNPG resources are included in k8s/base/:

• cnpg-cluster.yaml
• cnpg-pooler.yaml

CNPG bootstrap credentials are provided via SealedSecrets in overlays:

• k8s/overlays/release/cnpg-sealedsecret.yaml
• k8s/overlays/staging/cnpg-sealedsecret.yaml

The image is GPU-first. It is based on the official PyTorch runtime image with CUDA 12.8 and cuDNN 9 preinstalled, so the Docker build does not download the large torch/CUDA Python wheels again. The Kubernetes GPU Operator must still provide the node driver, device plugin and NVIDIA container runtime hooks.

Run locally with:

docker run --gpus all -p 5000:5000 -e OPENAI_API_KEY=sk-... audiodeskription-webapp

When changing the PyTorch version, keep the Docker base image tag aligned with the torch/torchaudio versions in uv.lock.

End-to-end UI tests use Playwright:

cd webapp
npm install          # install Playwright
npm run test         # or: npx playwright test

The backend must be running on http://localhost:5000 before executing tests.