MV Face Recognition Processor

Process video files from ViuTV's 全民造星 IV competition to detect and identify contestant faces using face recognition technology.

Overview

This skill helps you work with a face recognition video processing system that:

Critical Files to Protect

**NEVER delete, move, or modify without explicit user permission:**

**NEVER restore legacy files:**

Step-by-Step Instructions

1. Understanding the Architecture

When working with this system, recognize these key components:

2. Setting Up Development Environment

**First-time setup:**

```bash

Clone and setup environment

git clone https://github.com/yellowcandle/mv-face-recognition.git

cd mv-face-recognition

node scripts/setup-environment.js

```

**Download contestant data from HuggingFace:**

```bash

python scripts/upload_dataset_to_hf.py --download-only --download-dir source/photo/contestants

```

3. Processing Videos

**Option A - Full automated pipeline (recommended):**

```bash

node scripts/run-full-pipeline.js

```

**Option B - Process individual video:**

```bash

cd mvp-processor

python process_video.py --input ../source/videos/your-video.mp4

```

**Option C - Batch processing:**

```bash

Process all videos in source/videos directory

node scripts/batch-process-videos.js

```

4. Building Frontend

**Always build from mvp-processor directory:**

```bash

cd mvp-processor

npm run build

```

**Verify SvelteKit build:**

```bash

Should show _app directory with embedded assets

ls -la build/_app/

```

5. Deploying to Cloudflare

**Automated deployment:**

```bash

From project root

node scripts/deploy-cloudflare.js

```

**Manual deployment steps:**

```bash

1. Build frontend

cd mvp-processor && npm run build && cd ..

2. Update worker assets

node scripts/update-worker-assets.js

3. Deploy worker

cd worker && wrangler deploy

```

**Verify deployment:**

```bash

curl -s "https://mv-face-recognition-api.herballemon.workers.dev/" | head -10

```

6. Running Tests

**Frontend tests:**

```bash

cd frontend

npm run test # Unit + component tests

npm run test:e2e # Playwright E2E tests

npm run test:coverage # Coverage report

```

**Python tests:**

```bash

cd mvp-processor

pytest tests/ --cov=. --cov-report=html

```

**Worker tests:**

```bash

cd worker

npm test

```

7. Managing Contestant Data

**Upload new photos to HuggingFace:**

```bash

Ensure HF_TOKEN is set: export HF_TOKEN=your_token

python scripts/upload_dataset_to_hf.py --upload

```

**NEVER add photos back to Git:**

8. Documentation Requirements

**Always document changes in DESIGN.md:**

**NEVER modify README.md without explicit permission**

Important Constraints

Data Storage Rules

1. Contestant photos live on HuggingFace, NOT in Git

2. Download photos before face recognition processing

3. Use `upload_dataset_to_hf.py` for all photo management

4. Rate limit: 256 commits/hour on HuggingFace (use batch uploads)

Frontend Configuration Rules

1. Frontend is ONLY in `mvp-processor/` directory

2. Use SvelteKit 2.x, NOT legacy Vite+Svelte

3. Build command MUST use `sveltekit()` plugin in vite.config.js

4. Verify `_app/` directory exists after build

Deployment Rules

1. Always test build before deploying to Cloudflare

2. Verify asset embedding includes `_app/` directory

3. Check all routes work: /, /video-player, /processing, /analytics

4. Test video player shows actual videos, not placeholders

Testing Rules

1. Maintain coverage thresholds: Frontend 85%+, Python 80%+, Worker 90%+

2. Run integration tests before deployment

3. Never lower coverage requirements without justification

4. All 5 CI/CD jobs must pass before merge

Common Issues & Solutions

**Issue: Photos missing locally**

```bash

Download from HuggingFace

python scripts/upload_dataset_to_hf.py --download-only --download-dir source/photo/contestants

```

**Issue: Deployment serves wrong app**

```bash

Rebuild SvelteKit properly

cd mvp-processor && rm -rf build && npm run build

Verify _app directory

ls -la build/_app/

Re-deploy

cd .. && node scripts/update-worker-assets.js && cd worker && wrangler deploy

```

**Issue: Face recognition not working**

```bash

Verify contestant database

cat metadata/contestant_info.csv | wc -l # Should be 97 (96 + header)

Check embeddings exist

ls -la source/photo/contestants/*/embeddings/

```

**Issue: Tests failing**

```bash

Update test snapshots if UI changed intentionally

cd frontend && npm run test -- -u

Check Python dependencies

cd mvp-processor && pip install -r requirements.txt

```

Routes & API Endpoints

**Frontend Routes:**

**API Endpoints** (21 total):

Performance Optimization

**Video Processing:**

**Frontend:**

**Storage:**

Example Usage

**Complete workflow for new video:**

```bash

1. Add video to source directory

cp new-episode.mp4 source/videos/

2. Ensure contestant data is downloaded

python scripts/upload_dataset_to_hf.py --download-only --download-dir source/photo/contestants

3. Process video

cd mvp-processor

python process_video.py --input ../source/videos/new-episode.mp4

4. Build and deploy

cd ..

node scripts/run-full-pipeline.js

```

Resources

Notes for AI Assistants