DOCSEARCHbyAlgolia
Submit Docs

Vylux Documentation

website·Indexed 30 days ago

https://carry0987.github.io/Vylux

A standalone media processing service for real-time image transformation and asynchronous media handling. Vylux provides capabilities for image conversion via /img, video processing through POST /api/video/jobs, and audio processing via POST /api/audio/jobs. It supports HLS + CMAF raw-key encryption (cbcs) for protected playback and utilizes a binary architecture with an HTTP server, queue worker, PostgreSQL, Redis, and S3-compatible storage.

Tokens
38.1K
Snippets
158
Records
271
Agent score
70%

What's inside Vylux

  1. Overview of Vylux media processing capabilities

    Vylux is a standalone media processing service that handles real-time image transformation and asynchronous media processing. It accepts source objects, validation data, and processing parameters to produce cacheable, traceable, and playable media assets. Core capabilities include:

    • Real-time image transformation via /img (resize, format conversion, and caching).
    • Signed delivery of originals and thumbnails via /original and /thumb.
    • Asynchronous audio and video job creation via /api/audio/jobs and /api/video/jobs.
    • Audio outputs: HLS playback, MP3, FLAC, and waveform generation.
    • Video outputs: HLS CMAF with AV1 and H.264 ladders, including portrait and non-16:9 sizing.
    • Encrypted playback: Bearer-token key delivery via /api/key/{id} using raw-key CBCS / SAMPLE-AES protection.
    • Infrastructure integration: PostgreSQL for job state, Redis for queues, Prometheus for metrics, and OpenTelemetry for tracing.

  2. Vylux Service Overview

    Vylux is a standalone media processing service designed to decouple real-time image transformation and asynchronous media processing into independently deployable capabilities. It does not handle business logic; instead, it receives source objects, validates information and processing parameters, and outputs cacheable, trackable, and playable media assets.

  3. Vylux System Architecture Overview

    Vylux is designed to handle two distinct workloads within a single service: synchronous image delivery and asynchronous audio/video processing jobs. It maintains consistent conventions across storage, queueing, and routing for both workload types.

  4. Understand Vylux Docker image startup semantics

    The Vylux Docker image is configured with a default entrypoint and command to allow it to work out-of-the-box while remaining flexible for production roles. The default behavior is to run in all mode, but this can be overridden in Docker, Docker Compose, or Kubernetes by passing different arguments.
    ENTRYPOINT ["vylux"]
CMD ["--mode=all"]

  5. Vylux System Architecture and Execution Model

    Vylux operates as a single service that handles two distinct types of workloads: synchronous image services and asynchronous audio/video tasks. This unified approach ensures consistency across storage, queues, and routing conventions.

  6. Vylux Media Processing Pipelines

    Vylux utilizes a set of specialized tools for its media pipelines: FFmpeg and ffprobe are used for analysis and encoding, while Shaka Packager is used to generate HLS outputs. The system supports the creation of audio artifacts, video ladders, and encrypted key delivery.

  7. Understand Vylux integration responsibilities

    Vylux handles media processing and delivery semantics, while the application handles access control.

    Vylux is responsible for:

    • Processing source media into derived outputs.
    • Serving signed image and media-delivery endpoints.
    • Serving HLS playlists and segments via /stream/{hash}/*.
    • Validating Bearer tokens for /api/key/{id}.

    The application is responsible for:

    • Deciding which end user is allowed to see a specific asset.
    • Minting business-layer auth tokens or session cookies.
    • Storing authorization policies.
    • Converting internal storage keys (from job results) into signed public URLs.

  8. Vylux Integration Responsibility Model

    Vylux is designed to handle media processing and delivery, while the upstream application manages access control and authorization.

    Vylux Responsibilities:

    • Processing source media into various outputs.
    • Providing signed endpoints for images and media delivery.
    • Providing HLS playlist and segment access via /stream/{hash}/*.
    • Validating Bearer tokens for /api/key/{id}.

    Application Responsibilities:

    • Determining which end-users can access specific media.
    • Issuing business-level auth tokens or sessions.
    • Storing authorization rules.
    • Generating HMAC signatures for image URLs and Bearer tokens for playback.

  9. Vylux system architecture and component responsibilities

    Vylux relies on a set of shared infrastructure components to handle media processing and delivery. The responsibilities are split between the HTTP server (synchronous/API) and the Worker (asynchronous processing).

    Component Responsibility Matrix

    ComponentPrimary Responsibility
    HTTP serverAPI endpoints (/img, /original, /thumb, /api/jobs, /stream, /api/key), health checks, and metrics.
    WorkerConsuming async tasks, downloading source media, executing audio/video processing, and writing results/webhooks.
    PostgreSQLPersistence for jobs, workflow results, retry metadata, wrapped content keys, and image cache tracking.
    RedisAsynq queue, task state, and API/key endpoint rate limiting.
    Source storeRead-only storage for original source objects (configured via SOURCE_BUCKET and SOURCE_S3_*).
    Media storeRead/Write storage for processed assets: thumbnails, covers, previews, HLS playlists, and segments (configured via MEDIA_BUCKET and MEDIA_S3_*).
    Media toolchainvips (images), FFmpeg/ffprobe (video encoding/probing), Shaka Packager (HLS CMAF packaging).

  10. Generate playback Bearer tokens for key delivery

    Bearer tokens for the /api/key/{id} endpoint are composed of two base64url fragments: a JSON payload and an HMAC-SHA256 signature. The signature is calculated over the base64url payload string using the KEY_TOKEN_SECRET.

    Token Format: base64url({"hash":"...","exp":<unix_timestamp>}).base64url(HMAC-SHA256(payload_b64, KEY_TOKEN_SECRET))

    Security Warning:

    • Keep KEY_TOKEN_SECRET in a trusted backend; never expose it to the browser.
    • Do not place Bearer tokens in playlist or segment URLs.
    • Tokens should be short-lived.
    MEDIA_HASH='movie-2026-04-01'
KEY_ID='replace-with-key-id'
KEY_TOKEN_SECRET='replace-with-key-token-secret'

# 1. Create JSON payload with hash and expiration (1 hour)
PAYLOAD="$(jq -cn 
    --arg hash "$MEDIA_HASH" 
    --argjson exp "$(($(date +%s) + 3600))" 
    '{hash: $hash, exp: $exp}')"

# 2. Base64url encode the payload
PAYLOAD_B64="$(printf '%s' "$PAYLOAD" 
    | openssl base64 -A 
    | tr '+/' '-_' 
    | tr -d '=')"

# 3. Sign the base64url payload using HMAC-SHA256
SIG_B64="$(printf '%s' "$PAYLOAD_B64" 
    | openssl dgst -sha256 -mac HMAC -macopt "key:$KEY_TOKEN_SECRET" -binary 
    | openssl base64 -A 
    | tr '+/' '-_' 
    | tr -d '=')"

TOKEN="$PAYLOAD_B64.$SIG_B64"

  11. Submit asynchronous media jobs

    Jobs for audio and video are submitted via POST requests. The server performs request fingerprinting to ensure idempotency before enqueueing:

    1. Validate API key and payload.
    2. Perform an idempotency check based on type + hash + source + canonicalized options.
    3. If an active job or completed result exists, return it immediately.
    4. Otherwise, enqueue the task to Redis/asynq and create a PostgreSQL job row with status queued.

    For audio and streaming video jobs, the server verifies the object's existence and size in the source store before enqueueing. A 202 Accepted response indicates the request has passed validation and the issue boundary has shifted to the worker execution.

    POST /api/audio/jobs
POST /api/video/jobs

  12. Securely implement Vylux URL signing

    To prevent unauthorized access and security leaks, follow these guidelines:

    1. Keep HMAC_SECRET private: Never expose the secret to browsers or public clients. Generate signed URLs server-side in your application backend, a dedicated signing service, or a trusted edge worker.
    2. Server-Side Flow:
      • User requests an asset.
      • Application verifies user permissions.
      • Application signs the Vylux URL server-side using HMAC_SECRET.
      • Application returns the final signed URL to the browser.
    3. Predictable Caching: Use stable object keys or content hashes to ensure CDN caching remains consistent.