Skip to content

Getting started

Jump to bottom
Gustav Grusell edited this page Dec 12, 2025 · 1 revision

Getting Started with Encore

Welcome to Encore, a scalable video transcoding service built on FFmpeg and Spring Boot. This guide will walk you through everything you need to get Encore up and running and submit your first transcoding job.

What is Encore?

Encore is a powerful video transcoding tool designed to make FFmpeg accessible and scalable. Instead of running complex FFmpeg commands manually, you define encoding profiles once and then submit transcoding jobs through a simple REST API. Encore handles the heavy lifting: queuing jobs, managing concurrent encodes, tracking progress, and delivering your transcoded files.

Key capabilities:

  • Submit transcoding jobs via REST API
  • Queue and prioritize encoding work
  • Scale horizontally by adding more workers
  • Define reusable encoding profiles
  • Track job progress and status
  • Support for segmented/chunked encoding for faster processing

Prerequisites

Before you start, you'll need:

  1. Docker and Docker Compose (recommended for quick start)

    Alternative: If you prefer running Encore directly, you'll need Java 21+ and FFmpeg/ffprobe/mediainfo installed and available in your PATH

  2. A test video file

    • Any video format supported by FFmpeg (MP4, MOV, MKV, etc.)
    • For this guide, we'll assume you have a file called sample.mp4

  3. Basic command-line knowledge

    • Running commands in a terminal
    • Using curl or similar HTTP tools

Quick Start with Docker Compose

The easiest way to get started is using Docker Compose, which will start both Encore and Redis together.

Step 1: Set Up Your Environment

First, create directories for your source videos and output files:

mkdir -p ~/Videos ~/encore-output

Place your test video (e.g., sample.mp4) in ~/Videos.

Step 2: Get the Docker Compose Configuration

Create a file called docker-compose.yml:

services:
  encore:
    image: eyevinn/encore:latest
    ports:
      - "8080:8080"
    environment:
      - SPRING_DATA_REDIS_HOST=redis
    volumes:
      - type: bind
        source: ${HOME}/Videos
        target: /video
      - type: bind
        source: ${HOME}/encore-output
        target: /output
  redis:
    image: "redis:alpine"

Step 3: Start Encore

Run the following command in the directory containing your docker-compose.yml:

docker compose up

You should see log output indicating that Encore is starting. Look for messages about connecting to Redis and the application starting successfully. The service will be available at http://localhost:8080.

Step 4: Verify Encore is Running

Open a new terminal and check that Encore is responding:

curl http://localhost:8080/encoreJobs

You should receive a JSON response with an empty list of jobs (or an object containing pagination information). This confirms Encore is running.

You can also view the API documentation by opening http://localhost:8080/swagger-ui.html in your web browser.

Understanding Encoding Profiles

Before submitting a job, you need to understand encoding profiles. A profile defines how your video should be encoded: resolution, bitrate, codec, audio settings, and more.

The Docker image includes several example profiles. Here's a simplified example of what a profile looks like:

name: simple-x264
description: Simple H.264 encode
scaling: bicubic
encodes:
  - type: X264Encode
    suffix: _720p
    height: 720
    params:
      b:v: 2000k        # Video bitrate
      r: 25             # Frame rate
      pix_fmt: yuv420p
    audioEncode:
      type: AudioEncode
      bitrate: 128k
      suffix: _STEREO

This profile creates a single output: 720p H.264 video with AAC audio at 128kbps.

The included program profile is more complex and creates multiple outputs at different resolutions (1080p, 720p, 540p, 360p, 234p) plus standalone audio files. For your first job, we'll use the program profile that's already included.

For more details on creating and customizing profiles, see Encoding-profiles.md.

Submitting Your First Transcoding Job

Now let's transcode a video. We'll submit a job using curl.

Create a Transcode Job

Run this command, replacing sample.mp4 with your actual filename:

curl -X POST http://localhost:8080/encoreJobs \
  -H 'Content-Type: application/json' \
  -d '{
    "profile": "program",
    "outputFolder": "/output",
    "baseName": "my-first-encode",
    "inputs": [{
      "uri": "/video/sample.mp4",
      "type": "AudioVideo"
    }]
  }'

What do these fields mean?

  • profile: The name of the encoding profile to use (we're using the built-in program profile)
  • outputFolder: Where to write the output files (inside the container, /output maps to ~/encore-output on your host)
  • baseName: The prefix for all output files (e.g., my-first-encode_x264_720p.mp4)
  • inputs: An array of input files. Each input has:
    • uri: Path to the input file (inside the container, /video maps to ~/Videos)
    • type: Type of input - AudioVideo, Audio, or Video

The response will include a job ID that looks like this:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "NEW",
  "profile": "program",
  "progress": 0,
  ...
}

Save the id value - you'll use it to check job status.

Checking Job Status

To monitor your job's progress, use the job ID from the previous step:

curl http://localhost:8080/encoreJobs/a1b2c3d4-e5f6-7890-abcd-ef1234567890

The response shows the current status and progress:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "IN_PROGRESS",
  "progress": 45,
  "message": "Encoding...",
  ...
}

Job statuses:

  • NEW: Job created but not yet queued
  • QUEUED: Job is waiting in the queue
  • IN_PROGRESS: Job is currently encoding
  • SUCCESSFUL: Job completed successfully
  • FAILED: Job encountered an error
  • CANCELLED: Job was cancelled by user

You can also list all jobs:

curl http://localhost:8080/encoreJobs

Retrieving Your Output

Once the job status is SUCCESSFUL, your transcoded files will be in the output directory you specified. Since we used /output in the job (which maps to ~/encore-output), check there:

ls -lh ~/encore-output

With the program profile, you'll see multiple output files:

my-first-encode_x264_1080p_STEREO.mp4
my-first-encode_x264_720p_STEREO.mp4
my-first-encode_x264_540p_STEREO.mp4
my-first-encode_x264_360p_STEREO.mp4
my-first-encode_x264_234p_STEREO.mp4
my-first-encode_STEREO.m4a
thumbnail.jpg
thumbnail-map.vtt

Each file corresponds to an encode definition in the profile. The _STEREO suffix indicates stereo audio, and the resolution is part of the filename.

What Just Happened? A Step-by-Step Breakdown

Let's review the entire workflow:

  1. You submitted a job via HTTP POST to the /encoreJobs endpoint with your input file, output location, and profile name

  2. Encore validated the job and created a job record in Redis with status NEW

  3. The job was queued in Redis with status QUEUED, ready for processing

  4. A job poller picked up the job and changed its status to IN_PROGRESS

  5. Encore read the profile to determine what outputs to create

  6. FFmpeg was invoked for each encode in the profile, with Encore building the appropriate FFmpeg command-line arguments

  7. Progress was tracked by parsing FFmpeg output and updating the job progress percentage

  8. Output files were written to the specified output folder

  9. Job status was updated to SUCCESSFUL and the job record was updated with completion time and output file information

All of this happened automatically based on your simple job submission.

Common Operations

Cancelling a Job

If you need to stop a running job:

curl -X POST http://localhost:8080/encoreJobs/JOB_ID/cancel

Viewing the Queue

To see what jobs are currently queued:

curl http://localhost:8080/queue

Filtering Jobs by Status

To see all completed jobs:

curl http://localhost:8080/encoreJobs/search/findByStatus?status=SUCCESSFUL

Available statuses: NEW, QUEUED, IN_PROGRESS, SUCCESSFUL, FAILED, CANCELLED

Setting Job Priority

Jobs with higher priority (0-100) are processed first. Add a priority when creating a job:

{
  "profile": "program",
  "outputFolder": "/output",
  "baseName": "urgent-encode",
  "priority": 80,
  "inputs": [{
    "uri": "/video/sample.mp4",
    "type": "AudioVideo"
  }]
}

Troubleshooting

Problem: Job status is stuck at NEW or QUEUED

  • Check that Encore is running and not just the API
  • Check the Encore logs with docker compose logs encore
  • Verify Redis is accessible

Problem: Job failed with status FAILED

  • Check the job's message field for error details: curl http://localhost:8080/encoreJobs/JOB_ID
  • Common issues:
    • Input file not found (check path is correct relative to container)
    • Invalid encoding profile
    • FFmpeg error (check FFmpeg supports your input format)

Problem: Cannot access the API

  • Verify Encore is running: docker compose ps
  • Check port 8080 is not in use by another application
  • Try curl -v http://localhost:8080/encoreJobs for more connection details

Problem: Output files not appearing

  • Verify the output folder is mounted correctly
  • Check write permissions on the output directory
  • Check that the job completed successfully (status SUCCESSFUL)

Next Steps

Now that you've successfully transcoded your first video with Encore, you can:

  • Create custom encoding profiles - Learn how to define profiles that match your specific needs in Encoding-profiles.md
  • Explore the API - See all available endpoints and options in API-and-job-submission.md
  • Configure Encore - Customize settings like concurrency, Redis connection, and more in Configuring-encore.md
  • Deploy for production - Learn about scaling, high availability, and production deployments in Deploying-encore.md
  • Use advanced features - Explore chunked encoding for faster processing, S3 integration, progress callbacks, and more in the other wiki pages

Running Without Docker (Advanced)

If you prefer to run Encore directly without Docker:

  1. Install prerequisites:

    • Java 21 or later
    • FFmpeg, ffprobe, and mediainfo in your PATH
    • Redis server running

  2. Download the latest Encore release from the GitHub releases page

  3. Create a profiles file (see Encoding-profiles.md)

  4. Set environment variables:

    export PROFILE_LOCATION=file:///path/to/profiles.yml
export SPRING_DATA_REDIS_HOST=localhost

  5. Run Encore:

    java -jar encore-web-VERSION.jar

The REST API will be available at http://localhost:8080.

Getting Help

  • API Documentation: Visit http://localhost:8080/swagger-ui.html for interactive API docs
  • Community Support: Join the Streaming Tech Slack
  • Issues: Report bugs or request features on GitHub

Happy transcoding!

Clone this wiki locally