VidSplice

🎥 Powerful and fast video processing tool: audio extraction, frame capture, GIF creation, and more.

Quick Start • Installation • Usage • API Documentation • Contributing • License

📋 Table of Contents

✨ Features
💻 System Requirements
🚀 Quick Start
🛠️ Installation
- Docker Installation
- Manual Installation
📖 Usage
📚 API Documentation
⚙️ Configuration
- SSL Configuration
📈 Performance
🔒 Security
🧪 Testing
🤝 Contributing
📝 Version History
🛣️ Roadmap
📄 License
📞 Contact

✨ Features

🎯 Feature	📝 Description
🎬 Video Processing	Extract silent video from source files
🔊 Audio Extraction	Extract audio tracks from video files
🖼️ Frame Capture	Extract key frames from videos at specified intervals
🎞️ GIF Creation	Generate animated GIFs from video segments
🖼️ Thumbnail Generation	Create thumbnails from video content
🔒 Security	JWT-based authentication and SSL/TLS support
🔄 Async Processing	Asynchronous video processing with progress tracking
📈 High Performance	Optimized C++ implementation with FFmpeg integration
🐳 Docker Support	Easy deployment with Docker and Docker Compose
🛡️ Fault Tolerance	Automatic error recovery and process continuation

💻 System Requirements

Core Requirements

C++17 compatible compiler
CMake 3.10+
FFmpeg and development libraries
4GB RAM (minimum)
2 CPU cores (recommended: 4+)

Libraries

📚 Boost (1.70+)
📝 spdlog (1.8+)
🔄 nlohmann/json (3.9+)
🐳 Docker and Docker Compose
🧪 GoogleTest

🚀 Quick Start

# Pull the Docker image from Docker Hub
docker pull yunusgungor/vidsplice:latest

# Start with Docker Compose
docker-compose up -d

# Check if the service is running
docker-compose ps

# Get a JWT token for authentication
curl -k -X POST https://localhost:8443/v1/auth \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "password"}' | jq

# Process a video file
TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXUyJ9..."
curl -k -X POST https://localhost:8443/v1/process \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: multipart/form-data" \
  -F "video=@test_video.mp4" | jq

# Check processing status
JOB_ID="5f700496-ec3d-4c4b-a5cd-67d91f486cf5"
curl -k -X GET "https://localhost:8443/v1/progress/$JOB_ID" \
  -H "Authorization: Bearer $TOKEN" | jq

🛠️ Installation

Docker Installation

VidSplice is available as a Docker image on Docker Hub. You can use it directly without building from source:

# Pull the latest image from Docker Hub
docker pull yunusgungor/vidsplice:latest

# Run with Docker Compose
docker-compose up -d

# Check service status
docker-compose ps

# View logs
docker-compose logs

# View last 50 lines of logs
docker-compose logs --tail=50

# Follow logs in real-time
docker-compose logs -f

# Stop the service
docker-compose down

Using Docker Compose

Create a docker-compose.yml file with the following content:

services:
  vidsplice:
    image: yunusgungor/vidsplice:latest
    ports:
      - "8080:8080"  # HTTP port
      - "8443:8443"  # HTTPS port
    environment:
      - TEMP_DIR=/app/temp
      - LOG_LEVEL=debug
      - JWT_SECRET=your_secure_secret_key
      - PORT=8443
      - MAX_THREADS=8
      - RATE_LIMIT=100
      - SSL_ENABLED=true
      - SSL_CERT_PATH=/etc/ssl/certs/vidsplice.crt
      - SSL_KEY_PATH=/etc/ssl/private/vidsplice.key
    volumes:
      - ./ssl/certs:/etc/ssl/certs
      - ./ssl/private:/etc/ssl/private
      - ./temp:/tmp/vidsplice
    restart: unless-stopped

Building from Source

If you prefer to build the Docker image yourself:

# Clone the repository
git clone https://github.com/yunusgungor/vidsplice.git
cd vidsplice

# Build the Docker image
docker-compose build

# Run with Docker Compose
docker-compose up -d --build

Resource Configuration

You can customize resource limits in docker-compose.override.yml:

version: '3'

services:
  video_service:
    deploy:
      resources:
        limits:
          cpus: "0.5"  # Limit to 50% of CPU
          memory: 1024M  # Limit to 1GB of RAM

Manual Installation

# Install dependencies (Ubuntu/Debian)
sudo apt-get update
sudo apt-get install -y \
  build-essential \
  cmake \
  libboost-all-dev \
  libssl-dev \
  libffmpeg-dev \
  uuid-dev

# Install dependencies (CentOS/RHEL)
sudo yum install -y \
  gcc-c++ \
  cmake \
  boost-devel \
  openssl-devel \
  ffmpeg-devel \
  libuuid-devel

# Install dependencies (macOS)
brew install \
  cmake \
  boost \
  openssl \
  ffmpeg \
  ossp-uuid

# Build the project
mkdir build && cd build
cmake ..
make -j$(nproc)

# Install the binary (optional)
sudo make install

# Start the service
./vidsplice

# Start with custom configuration
./vidsplice --port 9443 --temp-dir /tmp/custom

📖 Usage

The API service runs on port 8443 by default with SSL enabled.

🔑 Authentication

To obtain a JWT token:

# Basic authentication request
curl -k -X POST https://localhost:8443/v1/auth \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "password"}' | jq

# Store token in a variable
TOKEN=$(curl -k -s -X POST https://localhost:8443/v1/auth \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "password"}' | jq -r '.data.token')

# Verify token is stored correctly
echo $TOKEN

# Example successful response
{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXUyJ9.eyJhcGlfa2V5IjoiYWRtaW4iLCJleHAiOjE3NDIwNTgxODgsImlhdCI6MTc0MTk3MTc4OCwiaXNzIjoidmlkZW9fZXh0cmFjdCJ9.HlMFHTUiUEapO9V7ml4PmWMfAzsrE_Ppai7P3ASIiDc",
    "expires_in": 3600
  },
  "message": "Authentication successful",
  "success": true
}

🎬 Video Processing

To process a video file:

# Basic video processing request
curl -k -X POST https://localhost:8443/v1/process \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: multipart/form-data" \
  -F "video=@test_video.mp4" | jq

# Process a specific video file
curl -k -X POST https://localhost:8443/v1/process \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: multipart/form-data" \
  -F "video=@/path/to/your/video.mp4" | jq

# Process a large video file
curl -k -X POST https://localhost:8443/v1/process \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: multipart/form-data" \
  -F "video=@very_large_test_video.mp4" | jq

# Store job ID in a variable
JOB_ID=$(curl -k -s -X POST https://localhost:8443/v1/process \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: multipart/form-data" \
  -F "video=@test_video.mp4" | jq -r '.data.job_id')

# Example successful response
{
  "data": {
    "job_id": "5f700496-ec3d-4c4b-a5cd-67d91f486cf5",
    "audio": "/tmp/vidsplice/eadf844d-6771-41d8-a920-423180dd2402.aac",
    "frames": [
      "/tmp/vidsplice/1249fc4c-c2b2-4a84-b18f-08ac8153dd3c_1.jpg",
      "/tmp/vidsplice/1249fc4c-c2b2-4a84-b18f-08ac8153dd3c_2.jpg",
      "/tmp/vidsplice/1249fc4c-c2b2-4a84-b18f-08ac8153dd3c_3.jpg",
      "/tmp/vidsplice/1249fc4c-c2b2-4a84-b18f-08ac8153dd3c_4.jpg",
      "/tmp/vidsplice/1249fc4c-c2b2-4a84-b18f-08ac8153dd3c_5.jpg"
    ],
    "gif": "/tmp/vidsplice/885b3059-81bd-49ed-83b9-212c6d251435.gif",
    "thumbnail": "/tmp/vidsplice/5eac4db0-f7a1-4e50-97f0-e7362405135b.jpg",
    "video": "/tmp/vidsplice/de21f3de-2cb3-4a12-8655-028bd1556072.mp4"
  },
  "message": "Video processing started",
  "success": true
}

📊 Progress Tracking

To check processing status:

# Basic progress check
curl -k -X GET "https://localhost:8443/v1/progress/$JOB_ID" \
  -H "Authorization: Bearer $TOKEN" | jq

# Check progress with a specific job ID
curl -k -X GET "https://localhost:8443/v1/progress/5f700496-ec3d-4c4b-a5cd-67d91f486cf5" \
  -H "Authorization: Bearer $TOKEN" | jq

# Poll progress every 5 seconds
while true; do
  curl -k -s -X GET "https://localhost:8443/v1/progress/$JOB_ID" \
    -H "Authorization: Bearer $TOKEN" | jq
  sleep 5
done

# Check progress and wait until completion
while true; do
  RESPONSE=$(curl -k -s -X GET "https://localhost:8443/v1/progress/$JOB_ID" \
    -H "Authorization: Bearer $TOKEN")
  IS_COMPLETED=$(echo $RESPONSE | jq -r '.data.is_completed')
  echo $RESPONSE | jq
  
  if [ "$IS_COMPLETED" = "true" ]; then
    echo "Processing completed!"
    break
  fi
  
  sleep 5
  echo "Waiting for processing to complete..."
done

# Example response during processing
{
  "data": {
    "job_id": "5f700496-ec3d-4c4b-a5cd-67d91f486cf5",
    "stage": 2,
    "stage_name": "Extracting Frames",
    "progress": 40.0,
    "status_message": "Frame 2/5 extracted",
    "elapsed_seconds": 24,
    "is_completed": false,
    "has_error": false,
    "error_message": ""
  },
  "success": true
}

# Example response when completed
{
  "data": {
    "job_id": "5f700496-ec3d-4c4b-a5cd-67d91f486cf5",
    "stage": 8,
    "stage_name": "Completed",
    "progress": 100.0,
    "status_message": "Processing completed",
    "elapsed_seconds": 57,
    "is_completed": true,
    "has_error": false,
    "error_message": ""
  },
  "success": true
}

Health Check

To check the API health status:

# Basic health check
curl -k -X GET https://localhost:8443/v1/health | jq

# Example response
{
  "status": "healthy",
  "timestamp": 1741971798,
  "version": "1.0.0"
}

📚 API Documentation

API Endpoints

Endpoint	Method	Description
`/v1/auth`	POST	Obtain JWT token
`/v1/process`	POST	Start video processing
`/v1/progress/{job_id}`	GET	Check processing status
`/v1/health`	GET	Check API health status

Request and Response Examples

Authentication

Request:

POST /v1/auth HTTP/1.1
Host: localhost:8443
Content-Type: application/json

{
  "username": "admin",
  "password": "password"
}

Response:

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXUyJ9...",
    "expires_in": 3600
  },
  "message": "Authentication successful",
  "success": true
}

Video Processing

Request:

POST /v1/process HTTP/1.1
Host: localhost:8443
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXUyJ9...
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="video"; filename="test_video.mp4"
Content-Type: video/mp4

(binary data)
------WebKitFormBoundary7MA4YWxkTrZu0gW--

Response:

{
  "data": {
    "job_id": "5f700496-ec3d-4c4b-a5cd-67d91f486cf5",
    "audio": "/tmp/vidsplice/eadf844d-6771-41d8-a920-423180dd2402.aac",
    "frames": [
      "/tmp/vidsplice/1249fc4c-c2b2-4a84-b18f-08ac8153dd3c_1.jpg",
      "/tmp/vidsplice/1249fc4c-c2b2-4a84-b18f-08ac8153dd3c_2.jpg",
      "/tmp/vidsplice/1249fc4c-c2b2-4a84-b18f-08ac8153dd3c_3.jpg",
      "/tmp/vidsplice/1249fc4c-c2b2-4a84-b18f-08ac8153dd3c_4.jpg",
      "/tmp/vidsplice/1249fc4c-c2b2-4a84-b18f-08ac8153dd3c_5.jpg"
    ],
    "gif": "/tmp/vidsplice/885b3059-81bd-49ed-83b9-212c6d251435.gif",
    "thumbnail": "/tmp/vidsplice/5eac4db0-f7a1-4e50-97f0-e7362405135b.jpg",
    "video": "/tmp/vidsplice/de21f3de-2cb3-4a12-8655-028bd1556072.mp4"
  },
  "message": "Video processing started",
  "success": true
}

⚙️ Configuration

VidSplice can be configured using environment variables or by modifying the Docker Compose file:

Variable	Description	Default
`PORT`	Server port	8443
`TEMP_DIR`	Temporary directory for processing	/tmp/vidsplice
`JWT_SECRET`	Secret key for JWT tokens	default_secret_change_me
`JWT_EXPIRY`	JWT token expiry in seconds	3600
`SSL_ENABLED`	Enable SSL/TLS support	true
`SSL_CERT_PATH`	SSL certificate path	/etc/ssl/certs/vidsplice.crt
`SSL_KEY_PATH`	SSL private key path	/etc/ssl/private/vidsplice.key

Environment Variables

You can set environment variables in your Docker Compose file:

services:
  video_service:
    environment:
      - PORT=8443
      - TEMP_DIR=/tmp/vidsplice
      - JWT_SECRET=your_secure_secret_key
      - JWT_EXPIRY=3600
      - SSL_ENABLED=true
      - SSL_CERT_PATH=/etc/ssl/certs/vidsplice.crt
      - SSL_KEY_PATH=/etc/ssl/private/vidsplice.key

SSL Configuration

VidSplice provides SSL/TLS support for secure API access over HTTPS.

Generating SSL Certificates

For development environments, you can generate self-signed certificates:

# Create directories for SSL files
mkdir -p ssl/certs ssl/private

# Generate self-signed certificate
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout ssl/private/vidsplice.key \
  -out ssl/certs/vidsplice.crt \
  -subj "/C=US/ST=State/L=City/O=Organization/CN=localhost"

# Generate certificate with interactive prompts
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout ssl/private/vidsplice.key \
  -out ssl/certs/vidsplice.crt

# Verify certificate
openssl x509 -in ssl/certs/vidsplice.crt -text -noout

Enabling SSL

SSL is enabled by default. To configure it, set the following environment variables:

# Enable SSL
export SSL_ENABLED=true
export SSL_CERT_PATH=/etc/ssl/certs/vidsplice.crt
export SSL_KEY_PATH=/etc/ssl/private/vidsplice.key

# Start the service with SSL enabled
./vidsplice

When running with Docker Compose, these variables are already set in the docker-compose.yml file.

📈 Performance

VidSplice is optimized for efficient video processing:

Sequential processing of video operations
Efficient memory management
Optimized FFmpeg integration
Resource limiting to prevent system overload

Resource Configuration

You can adjust resource limits in the docker-compose.override.yml file:

services:
  video_service:
    deploy:
      resources:
        limits:
          cpus: "0.5"
          memory: 1024M

Monitoring Resource Usage

# Check Docker container resource usage
docker stats

# Check specific container stats
docker stats vidsplice-video_service-1

# One-time resource usage snapshot
docker stats --no-stream

🔒 Security

JWT-based authentication
SSL/TLS encryption
Input validation
File type verification
Resource limiting

🧪 Testing

# Run tests
cd build
cmake .. -DBUILD_TESTS=ON
make test

# Run specific test
ctest -R VideoProcessorTest

# Run tests with verbose output
CTEST_OUTPUT_ON_FAILURE=1 make test

# Generate test coverage report
cmake .. -DBUILD_TESTS=ON -DENABLE_COVERAGE=ON
make
make test
make coverage

🤝 Contributing

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📝 Version History

v1.0.0 (2024-03-15)
- Initial release
- Video, audio, frame, GIF, and thumbnail extraction
- JWT authentication
- SSL/TLS support
- Progress tracking

🛣️ Roadmap

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

📞 Contact

Yunus Güngör - @yunusgungor

Project Link: https://github.com/yunusgungor/vidsplice

Docker Hub: https://hub.docker.com/r/yunusgungor/vidsplice

Process your videos quickly and securely with VidSplice!

🔝 Back to Top

Name		Name	Last commit message	Last commit date
assets		assets
include		include
src		src
ssl		ssl
.dockerignore		.dockerignore
.gitignore		.gitignore
CMakeLists.txt		CMakeLists.txt
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
openapi.yaml		openapi.yaml
test_video.mp4		test_video.mp4

Latest commit

History

Folders and files

Repository files navigation

VidSplice

📋 Table of Contents

✨ Features

💻 System Requirements

Core Requirements

Libraries

🚀 Quick Start

🛠️ Installation

Docker Installation

Using Docker Compose

Building from Source

Resource Configuration

Manual Installation

📖 Usage

🔑 Authentication

🎬 Video Processing

📊 Progress Tracking

Health Check

📚 API Documentation

API Endpoints

Request and Response Examples

Authentication

Video Processing

⚙️ Configuration

Environment Variables

SSL Configuration

Generating SSL Certificates

Enabling SSL

📈 Performance

Resource Configuration

Monitoring Resource Usage

🔒 Security

🧪 Testing

🤝 Contributing

📝 Version History

🛣️ Roadmap

📄 License

📞 Contact

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages