UTEACH.AI

Webová aplikace pro automatický přepis přednášek a zvukových záznamů pomocí ASR (Automatic Speech Recognition).

Obsah

• Přehled projektu
• Struktura projektu
• Požadavky
• Instalace a spuštění
• API dokumentace
• Infrastruktura AWS
• CI/CD pipeline
• Testování
• Známé problémy

---

Přehled projektu

UTEACH.AI je Flask webová aplikace, která umožňuje:

• Nahrát zvukový soubor (MP3, WAV, OGG, FLAC, M4A, WEBM) nebo nahrát zvuk přímo z mikrofonu
• Přepsat audio do textu pomocí externího ASR servisu UWebASR (ZČU)
• Stáhnout výsledný přepis

Podporované jazyky: 🇨🇿 čeština, 🇸🇰 slovenština, 🇬🇧 angličtina, 🇩🇪 němčina, 🇵🇱 polština, 🇭🇺 maďarština, 🇭🇷 chorvatština, 🇷🇸 srbština, 🇳🇱 nizozemština.

---

Struktura projektu

uteach/
├── frontend/                        # Statický frontend
│   ├── index.html                   # Hlavní HTML stránka
│   ├── styles.css                   # Styly
│   ├── app.js                       # Logika UI a API volání
│   ├── MediaRecorder-MediaBackUp.js # Polyfill pro nahrávání
│   └── logo.png                     # Logo aplikace
│
├── backend/                         # Python backend (Flask)
│   ├── server.py                    # Hlavní Flask aplikace
│   ├── requirements.txt             # Python závislosti
│   ├── text.txt                     # Výstupní soubor posledního přepisu
│   └── tests/
│       └── test_app.py              # Automatické testy (pytest)
│
├── terraform/                       # Infrastruktura jako kód (AWS)
│   ├── main.tf                      # Provider konfigurace
│   ├── vpc.tf                       # VPC, subnety
│   ├── ecs.tf                       # ECS Fargate cluster a service + ECR
│   ├── alb.tf                       # Application Load Balancer
│   ├── security_groups.tf           # Security groups
│   ├── cloudwatch.tf                # Monitoring a alerty
│   ├── autoscaling.tf               # Auto Scaling
│   ├── s3.tf                        # S3 bucket pro assety
│   ├── outputs.tf                   # Výstupy (ALB URL, ECR URL…)
│   └── variables.tf                 # Proměnné
│
├── .github/workflows/
│   └── ci-cd.yml                    # GitHub Actions CI/CD pipeline
│
├── Dockerfile                       # Kontejnerová definice
├── .dockerignore
└── .gitignore

---

Požadavky

Lokální spuštění

Nástroj	Verze
Python	3.12+
pip	aktuální

Produkční nasazení

Nástroj	Verze
Docker	24+
Terraform	1.5+
AWS CLI	2.x

---

Instalace a spuštění

1. Klonování repozitáře

git clone https://github.com/honzas83/uteach.git
cd uteach
git checkout feature/frontend

2. Vytvoření virtuálního prostředí

python -m venv .venv

# Windows
.venv\Scripts\activate

# Linux / macOS
source .venv/bin/activate

3. Instalace závislostí

pip install -r backend/requirements.txt

4. Spuštění serveru

python backend/server.py

Aplikace je dostupná na http://127.0.0.1:5001

5. Spuštění v Dockeru

docker build -t uteach-app .
docker run -p 5001:5001 uteach-app

---

API dokumentace

Základní URL: http://localhost:5001

GET /health

Kontrola dostupnosti serveru.

Odpověď 200 OK:

{ "status": "ok" }

---

POST /transcribe

Odeslání zvukového souboru k přepisu. Přepis probíhá asynchronně na pozadí.

Tělo požadavku (multipart/form-data):

Pole	Typ	Povinné	Popis
file	soubor	✅	Zvukový soubor (MP3, WAV, OGG, FLAC, M4A, WEBM)
language	string	❌	Kód jazyka (výchozí: cs)

Kódy jazyků:

Kód	Jazyk
cs	Čeština
sk	Slovenština
en	Angličtina
de	Němčina
pl	Polština
hu	Maďarština
hr	Chorvatština
sr	Srbština
nl	Nizozemština

Odpověď 200 OK:

{ "task_id": "550e8400-e29b-41d4-a716-446655440000" }

Chybové odpovědi:

// 400 – chybí soubor
{ "error": "No file provided" }

// 400 – prázdný název souboru
{ "error": "No file selected" }

---

GET /status/<task_id>

Zjištění stavu přepisu. Volat opakovaně dokud status není done nebo error.

Parametry URL:

Parametr	Popis
task_id	UUID vrácené z /transcribe

Možné odpovědi:

// Zpracovává se
{ "status": "processing", "result": null, "error": null }

// Dokončeno
{ "status": "done", "result": "Přepsaný text přednášky...", "error": null }

// Chyba
{ "status": "error", "result": null, "error": "Popis chyby" }

// 404 – neznámé task_id
{ "error": "Task not found" }

---

Infrastruktura AWS

Produkční prostředí běží na AWS v regionu eu-central-1 a je celé spravováno Terraformem.

Architektura

Internet
   │
   ▼
Application Load Balancer  (port 80)
   │
   ▼
ECS Fargate Service  ←──────────  ECR Repository (Docker image)
   │  (port 5001, private subnets)
   │
   ├── eu-central-1a
   └── eu-central-1b
         │
         ▼
    S3 Bucket (statické assety)

Terraform nasazení

cd terraform

# Nastavení AWS přihlašovacích údajů
export AWS_ACCESS_KEY_ID="..."
export AWS_SECRET_ACCESS_KEY="..."
export AWS_SESSION_TOKEN="..."        # pouze pro dočasné přihlašovací údaje

terraform init
terraform plan
terraform apply

Windows (PowerShell):

$env:AWS_ACCESS_KEY_ID     = "..."
$env:AWS_SECRET_ACCESS_KEY = "..."
$env:AWS_SESSION_TOKEN     = "..."

Terraform proměnné

Proměnná	Výchozí hodnota	Popis
aws_region	eu-central-1	AWS region
project_name	webapp	Prefix pro pojmenování zdrojů
environment	prod	Prostředí (dev/staging/prod)
vpc_cidr	10.0.0.0/16	CIDR blok VPC
availability_zones	[eu-central-1a/b]	Seznam AZ
app_port	5001	Port aplikace

Terraform výstupy

Výstup	Popis
alb_dns_name	URL aplikace (ALB DNS)
ecr_repository_url	ECR URL pro docker push
ecs_cluster_name	Název ECS clusteru
ecs_service_name	Název ECS service
app_assets_bucket	Název S3 bucketu

---

CI/CD pipeline

Pipeline je definována v .github/workflows/ci-cd.yml a spouští se automaticky při každém push nebo Pull Requestu.

Přehled fází

push / PR
    │
    ▼
🔍 Lint ──────── py_compile, flake8, Hadolint (Dockerfile)
    │
    ▼
🧪 Test ──────── pytest (9 testů)
    │
    ▼
🏗️ Build ─────── docker build, spuštění kontejneru, health check, ověření statik
    │
    ▼
🛡️ Security ──── pip-audit (závislosti), Trivy (souborový systém)
    │
    ▼                    (pouze větev main)
🚀 Deploy ────── push do ECR → update ECS task → deploy s čekáním na stabilitu
    │
    ▼                    (pouze větev main)
💨 Smoke Test ── /health a homepage na živém ALB

Potřebné GitHub Secrets

Secret	Popis
AWS_ACCESS_KEY_ID	AWS přístupový klíč
AWS_SECRET_ACCESS_KEY	AWS tajný klíč
AWS_SESSION_TOKEN	Session token (pro dočasné přihlašovací údaje)

⚠️ Upozornění: Session tokeny mají omezenou dobu platnosti. Po vypršení je nutné aktualizovat všechny tři secrets v nastavení repozitáře.

---

Testování

Spuštění testů

pytest backend/tests/ -v

Pokrytí testů

Test	Co ověřuje
test_health_endpoint	GET /health vrací 200 a {"status": "ok"}
test_index_page	GET / vrací HTML stránku
test_static_css	GET /styles.css vrací 200
test_static_js	GET /app.js vrací 200
test_transcribe_no_file	POST /transcribe bez souboru vrací 400
test_transcribe_empty_file	POST /transcribe s prázdným názvem vrací 400
test_transcribe_returns_task_id	POST /transcribe s platným souborem vrací UUID
test_status_unknown_task	GET /status/<neznámé> vrací 404
test_status_after_transcribe	Status úlohy vrací správnou strukturu (processing/done/error)

---

Známé problémy

#	Závažnost	Popis
1	🔴 Vysoká	Výběr jazyka v UI nefunguje — #langSelect chybí v index.html, požadavky vždy odesílají s výchozím cs
2	🔴 Vysoká	Výběr mikrofonu se nepoužívá — vybraný deviceId se nepředává do getUserMedia()
3	🟡 Střední	AI sumarizace a generování PDF jsou pouze zástupné symboly bez skutečné implementace
4	🟡 Střední	text.txt je sdílený výstup pro všechny úlohy — souběžné požadavky si výsledky přepisují
5	🟡 Střední	Frontend nemá timeout ani tlačítko zrušení — při výpadku ASR servisu uživatel čeká donekonečna
6	🟢 Nízká	Stabilita závisí na externím ASR servisu uwebasr.zcu.cz