Voltage

<div align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="assets/voltage-logo-light.png"> <source media="(prefers-color-scheme: light)" srcset="assets/voltage-logo-dark.png"> <img alt="Voltage Logo" src="assets/voltage-logo-light.png" width="200"> </picture> </div> <div align="center">

Open-source, fully customizable, scalable, multi-instance, FFMPEG-based video encoding API service

</div>

---

---

📖 Introduction

Voltage is an enterprise-grade, open-source video encoding API service built for scale and flexibility. Designed and developed by Mustafa Ercan Zırh (@ercanzirh) and Faruk Gerçek (@favger) from RADAAR — an AI-powered social media management and automation platform.

Voltage enables you to process video content at scale with:

• Multi-instance architecture for horizontal scaling
• FFMPEG-based encoding with full customization
• Multiple storage backends (local, S3, FTP, SFTP, and more)
• Multiple database support (SQLite, MySQL, PostgreSQL, and more)
• AI-powered content analysis with Whisper transcription and NSFW detection
• RESTful API for easy integration
• Real-time monitoring with a modern web interface
• Job queue management with priority handling and retry mechanisms
• Webhook notifications for job status updates

Whether you're building a social media platform, video streaming service, or content management system, Voltage provides the robust infrastructure you need for reliable video processing at any scale.

---

🔄 Alternatives

While Voltage is built for flexibility and scale, you might also consider these alternatives:

Open Source

• Remotion - Create videos programmatically with React
• VideoFlow - Python-based video processing framework
• FFmpeg directly - Command-line multimedia framework (requires manual implementation)

Commercial Services

• Zencoder - Video and audio encoding API
• Coconut - Video encoding service & API for developers
• Mux - Video streaming and encoding API
• Cloudinary - Media management and transformation
• AWS Elemental MediaConvert - File-based video transcoding
• Azure Media Services - Cloud-based media workflows

Why Choose Voltage?

✅ Full control - Self-hosted, no vendor lock-in
✅ Cost-effective - No per-minute encoding fees
✅ Customizable - Built on FFMPEG with full flexibility
✅ Scalable - Multi-instance architecture
✅ AI-powered - Built-in transcription and content analysis
✅ Storage agnostic - Works with any storage backend

---

🛠️ Used Technologies

Voltage leverages industry-leading tools and libraries:

Core Processing

• FFMPEG - Advanced multimedia framework for video/audio encoding, decoding, and transcoding
• FFPROBE - Multimedia stream analyzer for extracting video metadata and specifications

AI & Machine Learning

• Whisper - OpenAI's automatic speech recognition (ASR) for audio transcription
  • Supports multiple models: TINY, BASE, SMALL, MEDIUM, LARGE variants
  • CUDA acceleration support for faster processing
• NSFWJS - Client-side indecent content checker
  • Models: MOBILE_NET_V2, MOBILE_NET_V2_MID, INCEPTION_V3
  • Configurable thresholds for content moderation

Backend & Framework

• Node.js with TypeScript - Runtime environment
• Express.js - Web application framework
• Knex.js - SQL query builder with multi-database support

Storage & Database

• Multiple database engines via Knex.js
• Cloud storage integration via AWS SDK and custom adapters
• Worker threads for parallel processing

Frontend

• React with TypeScript - UI framework
• Vite - Build tool and dev server
• Tailwind CSS - Utility-first CSS framework

---

💾 Supported Databases

Voltage supports multiple database engines for maximum flexibility:

| Database | Type | Use Case | | ---------------- | --------------- | ------------------------------- | | SQLite | Embedded | Development, small deployments | | MySQL | Relational | Production, shared hosting | | MariaDB | Relational | MySQL alternative | | PostgreSQL | Relational | Advanced features, JSON support | | MSSQL | Relational | Microsoft environments | | AWS Redshift | Data Warehouse | Analytics, large-scale data | | CockroachDB | Distributed SQL | Global distribution, resilience |

Configure via VOLTAGE_DATABASE_TYPE environment variable.

---

📦 Supported Storage Services

Voltage provides unified storage abstraction for multiple providers:

Cloud Storage (S3-Compatible)

• AWS S3 - Amazon Web Services
• Google Cloud Storage - Google Cloud Platform
• DigitalOcean Spaces - DigitalOcean's object storage
• Linode Object Storage - Akamai/Linode cloud storage
• Wasabi - Hot cloud storage
• Backblaze B2 - Low-cost cloud storage
• Rackspace Cloud Files - Rackspace cloud storage
• Microsoft Azure Blob Storage - Azure cloud storage
• Other S3-Compatible - Any S3 API compatible service

Traditional Storage

• Local Filesystem - Local disk storage
• FTP - File Transfer Protocol (with FTPS support)
• SFTP - SSH File Transfer Protocol

Configure via VOLTAGE_STORAGE_TYPE and related environment variables.

---

🚀 Installation

Prerequisites

• Node.js 18+ and pnpm package manager
• FFMPEG and FFPROBE binaries installed
• Database (optional - defaults to SQLite)
• Storage (optional - defaults to local filesystem)

Quick Start

1. Clone the repository

git clone https://github.com/radaario/voltage.git
cd voltage

2. Install dependencies

pnpm install

3. Configure environment variables

cp .env.example .env
# Edit .env with your configuration

4. Build the project

pnpm build

5. Start the services

pnpm start

Docker Deployment

docker-compose up -d --build

The service will be available at http://localhost:8080

Development Mode

# Start all services in development mode
pnpm dev

# Or start individual services
pnpm dev:api        # API server only
pnpm dev:runtime    # Runtime worker only
pnpm dev:frontend   # Frontend only

---

📡 API Endpoints

All endpoints return JSON responses with this structure:

{
	"metadata": {
		"version": "1.0.5",
		"env": "production",
		"status": "SUCCESSFUL"
	},
	"data": {}
}

Health & Configuration

GET /status or GET /health

Health check endpoint

• Auth: Not required
• Response: Service status

GET /config

Get service configuration

• Auth: Not required
• Response: Sanitized configuration object

---

Authentication

POST /auth

Authenticate to API/frontend

• Auth: Not required
• Body:
  • password (string) - Frontend password
• Response: Authentication token

---

Statistics

GET /stats

Fetch statistics for a date range

• Auth: Required
• Query Params:
  • since_at (string, optional) - Start date (YYYY-MM-DD)
  • until_at (string, optional) - End date (YYYY-MM-DD)
• Response: Array of daily statistics

DELETE /stats

Delete statistics

• Auth: Required
• Query Params:
  • all (boolean) - Delete all stats
  • stat_key (string) - Delete specific stat
  • date (string) - Delete stats for specific date
  • since_at (string) - Delete from date
  • until_at (string) - Delete until date

---

Logs

GET /logs

Fetch system logs

• Auth: Required
• Query Params:
  • log_key (string, optional) - Get specific log
  • limit (number, default: 25) - Results per page
  • page (number, default: 1) - Page number
  • type (string) - Filter by log type
  • instance_key (string) - Filter by instance
  • worker_key (string) - Filter by worker
  • job_key (string) - Filter by job
  • output_key (string) - Filter by output
  • notification_key (string) - Filter by notification
  • q (string) - Search query
• Response: Paginated logs array

DELETE /logs

Delete logs

• Auth: Required
• Query Params:
  • all (boolean) - Delete all logs
  • log_key (string) - Delete specific log
  • since_at (string) - Delete from date
  • until_at (string) - Delete until date

---

Instances

GET /instances

List all processing instances

• Auth: Required
• Query Params:
  • instance_key (string, optional) - Get specific instance
  • q (string) - Search query
• Response: Array of instances with workers

DELETE /instances

Delete instances

• Auth: Required
• Query Params:
  • all (boolean) - Delete a