znakovni.hr/GIF_REGENERATION_GUIDE.md

# 🎨 GIF Preview Regeneration Guide

## Overview

This guide explains how to regenerate GIF preview images for all videos in the Znakovni.hr database. This is necessary after deploying to production because video files have different UUIDs than in development.

## Problem

When you see 404 errors for GIF files like:
```
https://znakovni.matijaturk.from.hr/uploads/gifs/7-adresa-c9ce5c69-1768753308093.gif
Failed to load resource: the server responded with a status of 404
```

This means the GIF files don't exist on the production server because they were generated locally with different video UUIDs.

## Solutions

### Option 1: Web UI (Recommended) 🌐

**Easiest method - no terminal access needed!**

1. **Deploy the latest Docker image:**
   ```bash
   docker pull git.matijaturk.from.hr/johnny2211/znakovni.hr:latest
   docker-compose down
   docker-compose up -d
   ```

2. **Open the regeneration tool in your browser:**
   ```
   https://znakovni.matijaturk.from.hr/regenerate-gifs.html
   ```

3. **Login as admin** (if not already logged in)

4. **Click the "🔄 Start GIF Regeneration" button**

5. **Wait for completion** (may take several minutes depending on number of videos)

6. **View results** - The page will show:
   - Total videos processed
   - Number of successful GIF generations
   - Number of failures (if any)
   - Error messages for failed videos

7. **Refresh the dictionary page** to see the new GIF previews!

### Option 2: Docker Environment Variable 🐳

**Automatic regeneration on container startup:**

1. **Add to your docker-compose.yml or .env file:**
   ```yaml
   environment:
     - REGENERATE_GIFS=true
   ```

2. **Restart the container:**
   ```bash
   docker-compose down
   docker-compose up -d
   ```

3. **Check logs to monitor progress:**
   ```bash
   docker-compose logs -f
   ```

4. **Remove the environment variable after first run** to avoid regenerating on every restart

### Option 3: API Endpoint 🔧

**Direct API call (requires authentication):**

```bash
curl -X POST https://znakovni.matijaturk.from.hr/api/terms/regenerate-all-gifs \
  -H "Cookie: your-session-cookie" \
  -H "Content-Type: application/json"
```

**Response:**
```json
{
  "total": 6,
  "success": 6,
  "failed": 0,
  "errors": []
}
```

## What Gets Created

For each video in the database, the system will:

1. ✅ Extract frames from the video file
2. ✅ Generate a GIF preview with these settings:
   - **Width:** 300px (height auto-scaled)
   - **FPS:** 10 frames per second
   - **Duration:** 3 seconds
   - **Quality:** High (palette-based encoding)
3. ✅ Save GIF to `/uploads/gifs/` directory
4. ✅ Create database record with `kind: 'GIF'`
5. ✅ Delete old GIF files if they exist

## Expected Results

### On Dictionary Page:
- ✅ Words with videos → **Animated GIF preview**
- ✅ Words without videos → **📝 Emoji icon**
- ✅ Words with videos but no GIF → **"Nema pregleda" icon**

### In Admin Panel:
- ✅ Video and GIF displayed **side-by-side**
- ✅ **"Regenerate GIF" button** (🔄) for individual regeneration
- ✅ Green checkmark **"✓ GIF preview dostupan"**

## Troubleshooting

### GIFs still not showing after regeneration

1. **Check browser console** (F12) for 404 errors
2. **Verify GIF files exist** on server:
   ```bash
   ls -lh /path/to/uploads/gifs/
   ```
3. **Check database records:**
   ```bash
   docker exec -it znakovni-app sh
   cd packages/backend
   npx tsx scripts/check-gifs.ts
   ```

### Regeneration fails for some videos

- Check that video files exist in `/uploads/videos/`
- Verify ffmpeg is installed in the container
- Check container logs for specific error messages
- Ensure sufficient disk space for GIF files

### Permission errors

- Ensure `/uploads/gifs/` directory is writable
- Check file ownership and permissions

### GIFs return 404 but files exist on server

This was a nginx configuration issue (fixed in commit bc688e5):

**Problem:** nginx regex for static assets was catching ALL `.gif` files, including those in `/uploads/gifs/`, and trying to serve them from frontend `dist/` directory instead of proxying to backend.

**Solution:** Updated nginx.conf to exclude `/uploads/` path from static asset caching:
```nginx
# Before (broken):
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
    expires 1y;
    add_header Cache-Control "public, immutable";
}

# After (fixed):
location ~* ^/(?!uploads/).*\.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
    expires 1y;
    add_header Cache-Control "public, immutable";
}
```

The negative lookahead `(?!uploads/)` ensures files under `/uploads/` are proxied to backend, not served as static assets.

## Technical Details

- **GIF Generator:** Uses ffmpeg with two-pass palette optimization
- **File naming:** GIFs use same filename as video but with `.gif` extension
- **Database:** GIF records stored in `term_media` table with `kind='GIF'`
- **Cleanup:** Old GIF files and database records are deleted before regeneration

## Maintenance

### Regenerate single GIF (Admin UI)

1. Go to Admin → Terms
2. Click video icon (🎥) for the term
3. Click "Regenerate GIF" button (🔄)
4. Wait for completion

### Regenerate all GIFs (after bulk video upload)

Use Option 1 (Web UI) or Option 2 (Docker env var) from above.

---

**Last updated:** 2026-01-18
**Docker image:** `git.matijaturk.from.hr/johnny2211/znakovni.hr:latest`
**Digest:** `sha256:9d17eac2038678e8b65d54eb8a5f1b99974810f829ff414288deb849876db620`
**Latest commit:** `bc688e5` - Fix nginx configuration for GIF serving