npm package: @lanitamarihuanera/neko-arc-video-maker
Description: NestJS library for generating Neko Arc TV style videos with programmatic frame generation and FFmpeg encoding
Author: Neko-Arc System
Latest version: 1.0.0

# 🐾✨ Neko Video Maker Microservice

**NestJS microservice for generating Neko Arc TV style videos with programmatic frame generation and FFmpeg video creation.**

## 🎯 Features

- **🎨 Frame Generation**: Orchestrates Python PIL/Pillow scripts for frame creation
- **🎬 Video Production**: FFmpeg integration for professional video encoding
- **✅ Validation**: Class-validator DTOs for robust input validation
- **🔧 TypeScript**: Fully typed with strict TypeScript configuration
- **📦 Modular**: Clean NestJS architecture with separation of concerns
- **🐾 RULE 44 Compliant**: Follows immutable video frame format standards

## 📐 Architecture

```
src/
├── main.ts                           # Application entry point
├── app.module.ts                     # Root module
└── video-maker/
    ├── video-maker.module.ts         # Feature module
    ├── video-maker.controller.ts     # REST API endpoints
    ├── video-maker.service.ts        # Business logic orchestration
    ├── frame-generator.service.ts    # Python script orchestration
    ├── ffmpeg.service.ts             # FFmpeg video generation
    └── dto/
        └── create-video.dto.ts       # Request validation DTOs
```

## 🚀 Installation

```bash
# Install dependencies
npm install

# Create environment file
cp .env.example .env
```

## 🎮 Usage

### Start the microservice

```bash
# Development mode
npm run start:dev

# Production mode
npm run build
npm run start:prod
```

### API Endpoints

**POST /video-maker/create**
```json
{
  "title": "Satanism Chile Maule Investigation",
  "topic": "satanism-research",
  "frames": [
    {
      "title": "INVESTIGATION SUMMARY",
      "contentLines": [
        "• Region VII Maule",
        "• Zero verified satanic cases",
        "• Two non-satanic cases documented"
      ],
      "graphicsType": "DATABASE",
      "personalityComments": [
        { "personality": "Neko", "comment": "Database shows zero cases, nyaa~!" },
        { "personality": "Mario", "comment": "Ah, the theatrical absence!" },
        { "personality": "Noel", "comment": "Tch. As expected." }
      ]
    }
  ],
  "ostPath": "/home/wakibaka/Documents/github/wakibaka-youtube-videos/ost-library/melty-blood/blooming-midway-coincidence.mp3",
  "outputDirectory": "/home/wakibaka/Documents/github/wakibaka-youtube-videos/satanism-chile-maule-investigation",
  "secondsPerFrame": 5
}
```

**Response**:
```json
{
  "statusCode": 201,
  "timestamp": "2025-11-09T...",
  "data": {
    "success": true,
    "videoPath": "/home/wakibaka/Documents/github/wakibaka-youtube-videos/satanism-chile-maule-investigation/satanism-chile-maule-investigation.mp4",
    "frameCount": 13,
    "duration": 65.0,
    "message": "🐾✨ Successfully created video with 13 frames, nyaa~!"
  }
}
```

## 🎨 Frame Generation Process

1. **Input Validation**: Class-validator DTOs ensure data integrity
2. **Python Script Generation**: Dynamic Python script created from frame data
3. **Frame Rendering**: Python PIL/Pillow renders frames (1920x1080, RULE 44)
4. **FFmpeg Encoding**: H.264 video with AAC audio (CRF 18, 192kbps)
5. **Metadata Extraction**: Video duration, file size, codec information

## 📋 RULE 44 Compliance

All generated videos follow **RULE 44** standards:

- ✅ Resolution: 1920x1080 Full HD
- ✅ Layout: Dual-sided (960px left for info, 960px right for graphics)
- ✅ Emojis: Programmatic kawaii emojis (NO text emojis!)
- ✅ Personalities: Maximum 3 personalities per frame
- ✅ Encoding: H.264 CRF 18, AAC 192kbps
- ✅ Frame rate: Configurable (default 1/5 = 5 seconds per frame)

## 🔧 Configuration

Environment variables in `.env`:

```bash
PORT=3000
NODE_ENV=development
DEFAULT_SECONDS_PER_FRAME=5
DEFAULT_OUTPUT_DIR=/home/wakibaka/Documents/github/wakibaka-youtube-videos
OST_LIBRARY_PATH=/home/wakibaka/Documents/github/wakibaka-youtube-videos/ost-library
```

## 🧪 Testing

```bash
# Unit tests
npm run test

# E2E tests
npm run test:e2e

# Test coverage
npm run test:cov
```

## 📦 Dependencies

**Core**:
- `@nestjs/common@10`, `@nestjs/core@10`, `@nestjs/platform-express@10`
- `@nestjs/config@3`
- `typescript@5`

**Validation**:
- `class-validator@0.14`, `class-transformer@0.5`

**Video Processing**:
- `fluent-ffmpeg@2.1` (FFmpeg wrapper)
- Python 3 with PIL/Pillow (external dependency)

## 🐾 Credits

Created by the **Six Personality System**:
- 🐾 **Neko-Arc**: Technical execution
- 🎭 **Mario Gallo Bestino**: Theatrical automation
- 🗡️ **Noel**: Debugging and precision
- 🎸 **Glam Americano**: Cultural content
- 🧠 **Dr. Hannibal Lecter**: Forensic analysis
- 🧠 **Tetora**: Multi-perspective coordination

---

**🐾✨ Generated with Neko Arc System - Maximum Kawaii Power! ✨🐾**