Arsmedia API

Arsmedia API

---

Introduction

Arsmedia is a high-performance, enterprise-grade multimedia processing backend built with Spring Boot.
It provides a comprehensive set of media transformation capabilities for video, audio, and image content, with a strong focus on scalability, security, and clean integration.

The platform is designed to serve as a reliable backend for media-intensive applications, supporting complex processing pipelines while maintaining predictable performance and operational stability.

---

Core Capabilities

Video Processing

• Format conversion (AVI → MP4, WebM → MOV, and 50+ additional formats)
• Codec transcoding (H.264, H.265, VP9, AV1) with quality optimization
• Audio stream manipulation (extract, replace, merge)
• Non-destructive editing (cut, trim, merge without re-encoding)
• Visual transformations (resize, crop, rotate, mirror, flip)
• Subtitle and overlay handling (burn-in or separate streams)
• Advanced filtering (blur, sharpen, grayscale, watermark, custom effects)
• Intelligent compression with bitrate and quality control

Audio Processing

• Multi-format support (MP3, WAV, AAC, FLAC, OGG, and more)
• Bitrate adjustment and sample-rate conversion
• Channel mixing and audio enhancement
• Audio extraction from video sources
• Effects processing (normalization, volume control, echo, fade, equalizer)
• Precise mixing and composition of multiple tracks

Image Processing

• Format conversion (JPEG, PNG, WebP, AVIF, and 20+ formats)
• Frame extraction from videos at configurable intervals
• Media generation (videos and GIFs from image sequences)
• Image resizing, cropping, filtering, and enhancement
• Automatic thumbnail generation with smart cropping

---

Architecture & Technology Stack

Component	Technology
Language	Java 21
Framework	Spring Boot 3.5.9
Build System	Gradle
Database	PostgreSQL with Flyway migrations
Authentication	JWT, API Keys, Client Credentials
Media Engine	FFmpeg, Jaffree
Storage	AWS S3 (Transfer Manager)
Email	Resend Java SDK
File Analysis	Apache Tika
Messaging	RabbitMQ
Testing	Testcontainers, JUnit 5, GreenMail

---

Security Model

Arsmedia implements a layered security approach to protect both infrastructure and media operations.

Client Authentication

All non-public endpoints require client authentication via headers:

X-CLIENT-ID: <client_id>
X-CLIENT-SECRET: <client_secret>

For local development, secret validation may be relaxed to simplify testing.

User Authentication (JWT)

JWT access tokens are issued via the authentication endpoint:

POST /auth/token/token-pairs
Content-Type: application/json

{
  "username": "[email protected]",
  "password": "secure_password"
}

Administrative Endpoints

Administrative operations require triple authentication:

• Valid API key
• Client credentials
• JWT bearer token with administrative privileges

---

Getting Started

Prerequisites

• Java 21 or newer
• PostgreSQL 16 or newer
• FFmpeg 6.0 or newer
• Gradle 8.0 or newer

Installation & Deployment

Clone the repository:

git clone https://github.com/Abega1642/arsmedia.git
cd arsmedia

Install development tools:

make install

Configure environment variables:

cp .env.template .env
# Update values as needed

Build & Run

Build the application (with format check):

make build

Run locally:

make run

Run with development profile:

make dev

Docker Operations

Build Docker image:

make docker-build

Run Docker container:

make docker-run

Stop Docker container:

make docker-stop

Testing

Run all tests:

make test

Run unit tests only:

make test-unit

Run integration tests only:

make test-integration

Code Quality

Format code:

make format

Check code formatting:

make format-check

Run Qodana analysis:

make qodana

Run Semgrep security scan:

make semgrep

CI/CD Pipeline (Local Simulation)

Run CI build pipeline locally:

make ci-build

Run CI test pipeline locally:

make ci-test

Run CI format check locally:

make ci-format

Development Workflow

Download and cache dependencies:

make deps

Compile the application:

make compile

Build JAR file:

make jar

Verify development environment:

make verify

Health & Monitoring

Check application health:

make health-check

View container logs:

make docker-logs

Cleanup

Clean build artifacts:

make clean

Complete cleanup (including Docker):

make clean-all

Help

Show all available commands:

make help

Quality & Reliability

Testing Strategy

• Unit, integration, and end-to-end tests
• Real infrastructure testing using Testcontainers
• Minimum line coverage threshold enforced (50%)
• JaCoCo reporting and verification

Code Quality

• Static analysis via Qodana
• Google Java Format enforcement
• Dependency and security vulnerability scanning

---

Production Deployment

Environment	URL	Status
Production	https://arsmedia.onrender.com	Active

Monitoring

• Spring Boot Actuator enabled
• Health checks and metrics endpoints
• Custom metrics for media processing operations

---

API Documentation

Interactive Documentation

• Swagger UI available at /swagger-ui.html
• OpenAPI 3.0 specification located at doc/api.yaml
• Postman collections can be generated from the OpenAPI definition

Example Request

POST /api/v1/video/convert
Content-Type: multipart/form-data
X-CLIENT-ID: your-client-id
X-CLIENT-SECRET: your-client-secret

{
  "file": [binary data],
  "targetFormat": "mp4",
  "quality": "high",
  "outputResolution": "1080p"
}

---

Project Foundation

Arsmedia is built on top of the ar-infra-template, a production-ready Spring Boot infrastructure and architecture template.

For detailed architectural conventions and project structure, refer to: https://github.com/Abega1642/ar-infra-template.git

---

Maintainer & Contact

BackOps Engineer: Abegà Razafindratelo Email: [email protected] GitHub: https://github.com/Abega1642

---

License

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

---

Support

If this project is useful to you, consider giving it a star on GitHub.