core

README

Core

The cloud-native audio/video processing API.

datarhei Core is management for FFmpeg processes without development effort. It is a central interface for mapping AV processes, is responsible for design and management, and provides all necessary interfaces to access the video content. The included control for FFmpeg can keep all used functions reliable and executable without the need for software developers to take care of it. In addition, process and resource limitation for all FFmpeg processes protects the host system from application overload. The overall system gives access to current process values (CPU, RAM) and complete control of system resources and loads with statistical access to process data and current and historical logs.

Features

• Unrestricted FFmpeg process management
• Optimized for long-running tasks
• In-Memory- and Disk-Filesystem for media assets
• HTTP and RTMP services
• Let's Encrypt for HTTPS and RTMPS
• HLS/DASH Session tracking with bandwidth and current viewer limiters
• Multiple resource limiters and monitoring
• FFmpeg progress data
• Metrics incl. Prometheus support
• Logging and debugging for FFmpeg processes with history
• Multiple auth. by JWT and Auth0
• 100% JSON REST API (Swagger documented)
• GraphQL for metrics, process, and progress data

Quick start

1. Run the Docker image

docker run --name core -d \
    -e CORE_API_AUTH_USERNAME=admin \
    -e CORE_API_AUTH_PASSWORD=secret \
    -p 8080:8080 \
    -v ${HOME}/core/config:/core/config \
    -v ${HOME}/core/data:/core/data \
    datarhei/core:latest

1. Open Swagger http://host-ip:8080/api/swagger/index.html

2. Log in with Swagger Authorize > Basic authorization > Username: admin, Password: secret

Docker images

Native (linux/amd64,linux/arm64,linux/arm/v7)

• datarhei/base:alpine-core-latest
• datarhei/base:ubuntu-core-latest

Bundle with FFmpeg (linux/amd64,linux/arm64,linux/arm/v7)

• datarhei/core:latest

Bundle with FFmpeg for Raspberry Pi (linux/arm/v7)

• datarhei/core:rpi-latest

Bundle with FFmpeg for Nvidia Cuda (linux/amd64)

• datarhei/core:cuda-latest

Bundle with FFmpeg for Intel VAAPI (linux/amd64)

• datarhei/core:vaapi-latest

Documentation

Environment variables

The environment variables can be set in the file .env, e.g.

CORE_API_AUTH_USERNAME=admin
CORE_API_AUTH_PASSWORD=datarhei
...

You can also provide them on the command line, whatever you prefer. If the same environment variable is set in the .env file and on the command line, the one set on the command line will overrule the one from the .env file.

The currently known environment variables (but not all will be respected) are:

Name	Default	Description
CORE_CONFIGFILE	(not set)	Path to a config file. The following environment variables will override the respective values in the config file.
CORE_ADDRESS	:8080	HTTP listening address.
CORE_LOG_LEVEL	info	silent, error, warn, info, debug.
CORE_LOG_TOPICS	(not set)	List of topics to log (comma separated)
CORE_LOG_MAXLINES	1000	Number of latest log lines to keep in memory.
CORE_DB_DIR	.	Directory for holding the operational data. This directory must exist.
CORE_HOST_NAME	(not set)	Set to the domain name of the host this instance is running on.
CORE_HOST_AUTO	true	Enable detection of public IP addresses.
CORE_API_READ_ONLY	false	Allow only ready only access to the API
CORE_API_ACCESS_HTTP_ALLOW	(not set)	Comma separated list of IP ranges in CIDR notation (HTTP traffic), e.g. 127.0.0.1/32,::1/128.
CORE_API_ACCESS_HTTP_BLOCK	(not set)	Comma separated list of IP ranges in CIDR notation (HTTP traffic), e.g. 127.0.0.1/32,::1/128.
CORE_API_ACCESS_HTTPS_ALLOW	(not set)	Comma separated list of IP ranges in CIDR notation (HTTPS traffic), e.g. 127.0.0.1/32,::1/128.
CORE_API_ACCESS_HTTPS_BLOCK	(not set)	Comma separated list of IP ranges in CIDR notation (HTTPS traffic), e.g. 127.0.0.1/32,::1/128.
CORE_API_AUTH_ENABLE	true	Set to false to disable auth for all clients.
CORE_API_AUTH_DISABLE_LOCALHOST	false	Set to true to disable auth for clients from localhost.
CORE_API_AUTH_USERNAME	(required)	Username for auth.
CORE_API_AUTH_PASSWORD	(required)	Password for auth.
CORE_API_AUTH_JWT_SECRET	(not set)	A secret for en- and decrypting the JWT. If not set, a secret will be generated.
CORE_API_AUTH_AUTH0_ENABLE	false	Enable Auth0.
CORE_API_AUTH_AUTH0_TENANTS	(not set)	List of base64 encoded Auth0 tenant JSON objects (comma-separated). The tenant JSON object is defined as {"domain":string,"audience":string,"users":array of strings}
CORE_TLS_ADDRESS	:8181	Port to listen on for HTTPS requests.
CORE_TLS_ENABLE	false	Set to true to enable TLS support.
CORE_TLS_AUTO	false	Set to true to enable automatic retrieval of a Let's Encrypt certificate. Requires CORE_TLS_ENABLE to be true and CORE_HOST_NAME to be set with CORE_HOST_AUTO to false.
CORE_TLS_CERTFILE	(not set)	TLS certificate file in PEM format.
CORE_TLS_KEYFILE	(not set)	TLS key file in PEM format.
CORE_STORAGE_DISK_DIR	.	A directory that will be exposed by HTTP on /. This directory must exist.
CORE_STORAGE_DISK_MAXSIZEMBYTES	0	Max. allowed megabytes for CORE_STORAGE_DISK_DIR.
CORE_STORAGE_DISK_CACHE_ENABLE	true	Enable cache for files from CORE_STORAGE_DISK_DIR.
CORE_STORAGE_DISK_CACHE_MAXSIZEMBYTES	0	Max. allowed cache size, 0 for unlimited.
CORE_STORAGE_DISK_CACHE_TTLSECONDS	300	Seconds to keep files in cache.
CORE_STORAGE_DISK_CACHE_MAXFILESIZEMBYTES	1	Max. file size to put in cache.
CORE_STORAGE_DISK_CACHE_TYPES	(not set)	List of file extensions to cache (space-separated, e.g. ".html .js"), empty for all.
CORE_STORAGE_MEMORY_AUTH_ENABLE	true	Enable basic auth for PUT,POST, and DELETE on /memfs.
CORE_STORAGE_MEMORY_AUTH_USERNAME	(not set)	Username for Basic-Auth of /memfs. Required if auth is enabled.
CORE_STORAGE_MEMORY_AUTH_PASSWORD	(not set)	Password for Basic-Auth of /memfs. Required if auth is enabled.
CORE_STORAGE_MEMORY_MAXSIZEMBYTES	0	Max. allowed megabytes for /memfs. Any value <= 0 means unlimited.
CORE_STORAGE_MEMORY_PURGE	false	Set to true to remove the oldest entries if the /memfs is full.
CORE_STORAGE_COCORE_ORIGINS	*	List of allowed CORS origins (comma separated). Will be used for / and /memfs.
CORE_STORAGE_MIMETYPES_FILE	mime.types	Path to file with MIME type definitions.
CORE_RTMP_ENABLE	false	Enable RTMP server.
CORE_RTMP_ENABLE_TLS	false	Enable RTMP over TLS (RTMPS). Requires CORE_TLS_ENABLE to be true.
CORE_RTMP_ADDRESS	:1935	RTMP server listen address.
CORE_RTMP_APP	/	RTMP app for publishing.
CORE_RTMP_TOKEN	(not set)	RTMP token for publishing and playing. The token is the value of the URL query parameter token.
CORE_FFMPEG_BINARY	ffmpeg	Path to FFmpeg binary.
CORE_FFMPEG_MAXPROCESSES	0	Max. allowed simultaneously running FFmpeg instances. Any value <= 0 means unlimited.
CORE_FFMPEG_ACCESS_INPUT_ALLOW	(not set)	List of pattern for allowed input URI (space-separated), leave emtpy to allow any.
CORE_FFMPEG_ACCESS_INPUT_BLOCK	(not set)	List of pattern for blocked input URI (space-separated), leave emtpy to block none.
CORE_FFMPEG_ACCESS_OUTPUT_ALLOW	(not set)	List of pattern for allowed output URI (space-separated), leave emtpy to allow any.
CORE_FFMPEG_ACCESS_OUTPUT_BLOCK	(not set)	List of pattern for blocked output URI (space-separated), leave emtpy to block none.
CORE_FFMPEG_LOG_MAXLINES	50	Number of latest log lines to keep for each process.
CORE_FFMPEG_LOG_MAXHISTORY	3	Number of latest logs to keep for each process.
CORE_PLAYOUT_ENABLE	false	Enable playout API where available
CORE_PLAYOUT_MINPORT	0	Min. port a playout server per input can run on.
CORE_PLAYOUT_MAXPORT	0	Max. port a playout server per input can run on.
CORE_DEBUG_PROFILING	false	Set to true to enable profiling endpoint on /profiling.
CORE_DEBUG_FORCEGC	0	Number of seconds between forcing GC to return memory to the OS. Use in conjuction with GODEBUG=madvdontneed=1. Any value <= 0 means not to force GC.
CORE_METRICS_ENABLE	false	Enable collecting historic metrics data.
CORE_METRICS_ENABLE_PROMETHEUS	false	Enable prometheus endpoint /metrics.
CORE_METRICS_RANGE_SECONDS	300	Seconds to keep history metric data.
CORE_METRICS_INTERVAL_SECONDS	2	Interval for collecting metrics.
CORE_SESSIONS_ENABLE	false	Enable HLS statistics for /memfs.
CORE_SESSIONS_IP_IGNORELIST	(not set)	Comma separated list of IP ranges in CIDR notation, e.g. 127.0.0.1/32,::1/128.
CORE_SESSIONS_SESSION_TIMEOUT_SEC	30	Timeout of a session in seconds.
CORE_SESSIONS_PERSIST	false	Whether to persist the session history. Will be stored in CORE_DB_DIR.
CORE_SESSIONS_MAXBITRATE_MBIT	0	Max. allowed outgoing bitrate in mbit/s, 0 for unlimited.
CORE_SESSIONS_MAXSESSIONS	0	Max. allowed number of simultaneous sessions, 0 for unlimited.
CORE_ROUTER_BLOCKED_PREFIXES	/api	List of path prefixes that can't be routed.
CORE_ROUTER_ROUTES	(not set)	List of route mappings of the form [from]:[to], e.g. /foo:/bar. Leave empty for no routings.
CORE_ROUTER_UI_PATH	(not set)	Path to directory with files for a UI. It will be mounted to /ui and uses index.html as default index page.

Config

The minimum config file has to look like this:

{
    "version": 1
}

All other values will be filled with default values and persisted on disk. The entire default config file:

{
    "version": 1,
    "id": "[will be generated if not given]",
    "name": "[will be generated if not given]",
    "address": ":8080",
    "log": {
        "level": "info",
        "topics": [],
        "max_lines": 1000
    },
    "db": {
        "dir": "./config"
    },
    "host": {
        "name": [],
        "auto": true
    },
    "api": {
        "read_only": false,
        "access": {
            "http": {
                "allow": [],
                "block": []
            },
            "https": {
                "allow": [],
                "block": []
            }
        },
        "auth": {
            "enable": true,
            "disable_localhost": false,
            "username": "",
            "password": "",
            "jwt": {
                "secret": ""
            },
            "auth0": {
                "enable": false,
                "tenants": []
            }
        }
    },
    "tls": {
        "address": ":8181",
        "enable": false,
        "auto": false,
        "cert_file": "",
        "key_file": ""
    },
    "storage": {
        "disk": {
            "dir": "./data",
            "max_size_mbytes": 0,
            "cache": {
                "enable": true,
                "max_size_mbytes": 0,
                "ttl_seconds": 300,
                "max_file_size_mbytes": 1,
                "types": []
            }
        },
        "memory": {
            "auth": {
                "enable": true,
                "username": "admin",
                "password": "vxbx0ViqfA75P1KCyw"
            },
            "max_size_mbytes": 0,
            "purge": false
        },
        "cors": {
            "origins": [
                "*"
            ]
        },
        "mimetypes_file": "mime.types"
    },
    "rtmp": {
        "enable": false,
        "enable_tls": false,
        "address": ":1935",
        "app": "/",
        "token": ""
    },
    "ffmpeg": {
        "binary": "ffmpeg",
        "max_processes": 0,
        "access": {
            "input": {
                "allow": [],
                "block": []
            },
            "output": {
                "allow": [],
                "block": []
            }
        },
        "log": {
            "max_lines": 50,
            "max_history": 3
        }
    },
    "playout": {
        "enable": false,
        "min_port": 0,
        "max_port": 0
    },
    "debug": {
        "profiling": false,
        "force_gc": 0
    },
    "stats": {
        "enable": true,
        "ip_ignorelist": [
            "127.0.0.1/32",
            "::1/128"
        ],
        "session_timeout_sec": 30,
        "persist": false,
        "persist_interval_sec": 300,
        "max_bitrate_mbit": 0,
        "max_sessions": 0
    },
    "service": {
        "enable": false,
        "token": "",
        "url": "https://service.datarhei.com"
    },
    "router": {
        "blocked_prefixes": [
            "/api"
        ],
        "routes": {}
    }
}

If you don't provide a path to a config file, the default config will be used, and nothing will be persisted to the disk. Default values can be overruled by environment variables.

TLS / HTTPS

Enable TLS / HTTPS support by setting CORE_TLS_ENABLE=true and provide the certificate file and key file in PEM format by setting the environment variables CORE_TLS_CERTFILE and CORE_TLS_KEYFILE accordingly. If a certificate authority signs the certificate, the certificate file should be the concatenation of the server's certificate, any intermediates, and the CA's certificate.

If TLS with given certificates is enabled, an HTTP server listening on CORE_ADDRESS (address) will be additionally started. This server provides access to the same memory filesystem as the HTTPS server (including limits and authorization), but its access is restricted to localhost only.

Let's Encrypt

If you want to use automatic certificates from Let's Encrypt, set the environment variable CORE_TLS_AUTO to true. To work, the environment variables CORE_TLS_ENABLE have to be true, and CORE_HOST_NAME has to be set to the host this host will be reachable. Otherwise, the ACME challenge will not work. The environment variables CORE_TLS_CERTFILE and CORE_TLS_KEYFILE will be ignored.

If automatic TLS is enabled, the HTTP server (CORE_ADDRESS, resp. address) must listen on port 80. It is required to automatically acquire the certificate (serving the HTTP-01 challenge). As a further requirement, CORE_HOST_NAME (host.name) must be set because it is used a the canonical name for the certificate.

The obtained certificates will be stored in CORE_DB_DIR/cert to be available after a restart.

The obtained certificates will be stored in CORE_DB_DIR/cert to be available after a restart.

Self-Signed certificates

To create a self-signed certificate and key file pair, run this command and provide a reasonable value for the Common Name (CN). The CN is the fully qualified name of the host the instance is running on (e.g., localhost). You can also use an IP address or a wildcard name, e.g., *.example.com.

RSA SSL certificate

openssl req -newkey rsa:2048 -nodes -keyout key.pem -x509 -days 365 -out cert.pem -subj '/CN=localhost'

ECDSA SSL certificate

openssl ecparam -name secp521r1 -genkey -out key.pem
openssl req -new -x509 -key key.pem -out cert.pem -days 365 -subj '/CN=localhost'

Call openssl ecparam -list_curves to see all available supported curves listed.

Access Control

To control who has access to the API, a list of allowed IPs can be defined. This list is provided at startup with the environment variables CORE_API_ACCESS_HTTP_BLOCK and CORE_API_ACCESS_HTTP_ALLOW. This is a comma-separated list of IPs in CIDR notation, e.g. 127.0.0.1/32,::1/128. If the list is empty, then all IPs are allowed. If the list contains any invalid IP range, the server will refuse to start. This can be separately defined for the HTTP and HTTPS server if you have TLS enabled with the environment variables CORE_API_ACCESS_HTTPS_BLOCK and CORE_API_ACCESS_HTTPS_ALLOW.

Input/Output Control

To control where FFmpeg can read and where FFmpeg can write, you can define a pattern that matches the input addresses or the output addresses. These patterns are regular expressions that can be provided at startup with the environment variables CORE_FFMPEG_ACCESS_INPUT and CORE_FFMPEG_ACCESS_OUTPUT. The expressions need to be space-separated, e.g. HTTPS?:// RTSP:// RTMP://. If one of the lists is empty, then no restriction on input, resp. The output will be applied.

Independently of the value of CORE_FFMPEG_ACCESS_OUTPUT there's a check that verifies that output can only be written to the specified CORE_STORAGE_DISK_DIR and works as follows: If the address has a protocol specifier other than file:, then no further checks will be applied. If the protocol is file: or no protocol specifier is given, the address is assumed to be a path that is checked against the path shown in CORE_STORAGE_DISK_DIR.

It will be rejected if the address is outside the CORE_STORAGE_DISK_DIR directory. Otherwise, the protocol file: will be prepended. If you give some expressions for CORE_FFMPEG_ACCESS_OUTPUT, you should also allow file:.

Special cases are the output addresses - (which will be rewritten to pipe:), and /dev/null (which will be allowed even though it's outside of CORE_STORAGE_DISK_DIR).

If you set a value for CORE_STORAGE_DISK_CACHE_MAXSIZEMBYTES, which is larger than 0, it will be interpreted as max—allowed megabytes for the CORE_STORAGE_DISK_DIR. As soon as the limit is reached, all processes that have outputs writing to CORE_STORAGE_DISK_DIR will be stopped. You are responsible for cleaning up the directory and restarting these processes.

RTMP

The datarhei Core includes a simple RTMP server for publishing and playing streams. Set the environment variable CORE_RTMP_ENABLE to true to enable the RTMP server. It is listening on CORE_RTMP_ADDRESS. Use CORE_RTMP_APP to limit the app a stream can be published on, e.g. /live to require URLs to start with /live. To prevent anybody can publish streams, set CORE_RTMP_TOKEN to a secret only known to the publishers. The token has to be put in the query of the stream URL, e.g. /live/stream?token=....

Method	Path	Description
GET	/api/v3/rtmp	List all currently published streams.

Playout

FFmpeg processes with a avstream: (or playout:) input stream can expose an HTTP API to control the playout of that stream. With CORE_PLAYOUT_ENABLE you enable exposing this API. The API is only exposed to localhost and is transparently connected to the datarhei Core API. You have to provide a port range (CORE_PLAYOUT_MINPORT and CORE_PLAYOUT_MAXPORT) where datarhei/core can use ports to assign it to the playout API.

Method	Path	Description
GET	/api/v3/process/:id/playout/:inputid/status	Retrieve the current status as JSON.
GET	/api/v3/process/:id/playout/:inputid/keyframe/*name	Retrieve the last deliverd key frame from the input stream as JPEG (if name has the ending .jpg) or PNG (if name has the ending .png).
GET	/api/v3/process/:id/playout/:inputid/errorframe/encode	Immediately encode the error frame to a GOP. Will only have an effect if the last key frame is currently in a loop.
PUT/POST	/api/v3/process/:id/playout/:inputid/errorframe/*name	Upload any image or video media that can be decoded and will be used to replace the key frame loop. If the key frame is currently in a loop, it will be repaced immediately. Otherwise, it will be used the next time the key frame is in a loop. The body of the request is the media file.
PUT	/api/v3/process/:id/playout/:inputid/stream	Replace the current stream. The body of the request is the URL of the new stream.

MIME Types

The file with the MIME types has one MIME type per line followed by a list of file extensions (including the ".").

text/plain  .txt
text/html   .htm .html
...

Memory Filesystem

AA very simple in-memory filesystem is available. The uploaded data is stored in a map, where the path used to upload the file is used as the key. Use the POST or PUT method with the proper direction for uploading a file. The body of the request contains the contents of the file. No particular encoding or Content-Type is required. The file can then be downloaded from the same path.

Method	Path	Description
POST	/memfs/*path	Upload a file to the memory filesystem. The filename is path which can contain slashes. If there's already a file with the same path, it will be overwritten.
PUT	/memfs/*path	Same as POST.
GET	/memfs/*path	Download the file stored under path. The MIME types are applied based on the extension in the path.
DELETE	/memfs/*path	Delete the file stored under path.
POST	/api/v3/memfs/*path	Upload a file to the memory filesystem.
PUT	/api/v3/memfs/*path	Same as POST.
GET	/api/v3/memfs/*path	Download the file stored under path.
PATCH	/api/v3/memfs/*path	Create a link to a file. The body contains the path to that file.
DELETE	/api/v3/memfs/*path	Delete the file stored under path.
GET	/api/v3/memfs	List all files that are currently stored in the in-memory filesystem.

Use these endpoints to, e.g., store HLS chunks and .m3u8 files (in contrast to an actual disk or a ramdisk):

ffmpeg -f lavfi -re -i testsrc2=size=640x480:rate=25 -c:v libx264 -preset:v ultrafast -r 25 -g 50 -f hls -start_number 0 -hls_time 2 -hls_list_size 6 -hls_flags delete_segments+temp_file+append_list -method PUT -hls_segment_filename http://localhost:8080/memfs/foobar_%04d.ts -y http://localhost:8080/memfs/foobar.m3u8

Then you can play it generally with, e.g., ffplay http://localhost:3000/memfs/foobar.m3u8.

Use the environment variables CORE_STORAGE_MEMORY_AUTH_USERNAME and CORE_STORAGE_MEMORY_AUTH_PASSWORD to protect the /memfs with Basic-Auth. Basic-Auth will only be enabled if both environment variables are set to non-empty values. The GET /memfs/:path will not be protected with Basic-Auth.

Use the environment variable CORE_STORAGE_MEMORY_MAXSIZEMBYTES to limit the amount of data that is allowed to be stored. The value is interpreted as megabytes. Use a value equal to or smaller than 0 not to impose any limits. A 507 Insufficient Storage will be returned if you hit the limit.

Listing all currently stored files is done by calling /v3/memfs with the credentials set by the environment variables CORE_API_AUTH_USERNAME and CORE_API_AUTH_PASSWORD. It also accepts the query parameter sort (name, size, or lastmod) and order (asc or desc). If a valid value for sort is given, the results are sorted in ascending order.

Routes

All contents in CORE_STORAGE_DISK_DIR are served from /. If you want to redirect some paths to an existing file, you can add static routes in router.routes by providing a direct mapping, e.g.

router: {
    routes: {
        "/foo.txt": "/bar.txt",
    }
}

The paths have to start with a /. Alternatively, you can serve whole directories from another root than CORE_STORAGE_DISK_DIR. Use a /* at the end of a path as key and a path on the filesystem as the target, e.g.

router: {
    routes: {
        "/ui/*": "/path/to/ui",
    }
}

If you use a relative path as target, then it will be added to the current working directory.

API

Check the detailed API description on /api/swagger/index.html.

Login / Auth

With auth enabled, you have to retrieve a JWT/OAuth token before you can access the /v3/ API calls.

Method	Path	Description
POST	/api/login	Retrieve a token to access the API.
GET	/api/v3/refresh_token	Retrieve a fresh token with a new expiry date.

For the login you have to send

{
    "username": "...",
    "password": "..."
}

The username and the password are set by the environment variables CORE_API_AUTH_USERNAME and CORE_API_AUTH_PASSWORD.

On successful login, the response looks like this:

{
    "expire": "2019-01-18T19:55:55+01:00",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1NDc4Mzc3NTUsImlkIjpudWxsLCJvcmlnX2lhdCI6MTU0NzgzNDE1NX0.ZcrpD4oRBqG3wUrfnh1DOVpXdUT7dvUnvetKFEVRKKc"
}

Use the token in all subsequent calls to the /api/v3/ endpoints, e.g.

http http://localhost:8080/api/v3/process "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1NDc4Mzc3NTUsImlkIjpudWxsLCJvcmlnX2lhdCI6MTU0NzgzNDE1NX0.ZcrpD4oRBqG3wUrfnh1DOVpXdUT7dvUnvetKFEVRKKc"

Config

Method	Path	Description
GET	/api/v3/config	Retrieve the current config without the override values from the environment variables.
GET	/api/v3/config/active	Retrieve the current config with the override values from the environment variables are taken into account.
PUT	/api/v3/config	Store a new config. Only some values are respected, and the new config will only be used after a restart.
GET	/api/v3/config/reload	Reload the config. The config will be re-read and validated from the store. It will cause a restart of all services.

When retrieving the config via the API, critical values (such as passwords) will be disguised if not required otherwise.

Process

With the process API call, you can manage different FFmpeg processes. A process is defined as:

{
    "id": "SomeId",
    "reference": "SomeId",
    "type": "ffmpeg",
    "input": [
        {
            "id": "inputid",
            "address": "rtsp://1.2.3.4/stream.sdp",
            "options": [
                ... list of input options ...
            ]
        },
        ... list of inputs ...
    ],
    "output": [
        {
            "id": "outputid",
            "address": "rtmp://rtmp.youtube.com/live2/...",
            "options": [
                ... list of output options ...
            ],
            "cleanup": [{
                "pattern": "(memfs|diskfs):...",
                "max_files: "number,
                "max_file_age_seconds": "number",
                "purge_on_delete: "(true|false)"
            }]
        },
        ... list of outputs ...
    ],
    "options": [
        ... list of global options ...
    ],
    "reconnect": (true|false),
    "reconnect_delay_seconds": 10,
    "autostart": (true|false),
    "stale_timeout_seconds": 30
}

The input, output, and global options are interpreted as command-line options for FFmpeg.

Process Cleanup

With the optional array of cleanup rules for each output, it is possible to define rules for removing files from the memory filesystem or disk. Each rule consists of a glob pattern and a max. allowed number of files matching that pattern or permitted maximum age for the files matching that pattern. The pattern starts with either memfs: or diskfs: depending on which filesystem this rule is designated to. Then a glob pattern follows to identify the files. If max_files is set to a number > 0, then the oldest files from the matching files will be deleted if the list of matching files is longer than that number. If max_file_age_seconds is set to a number > 0, then all files that are older than this number of seconds from the matching files will be deleted. If purge_on_delete is set to true, then all matching files will be deleted when the process is deleted.

The API calls are

Method	Path	Description
POST	/api/v3/process	Adds a process. Overwriting an existing ID will result in an error.
GET	/api/v3/process	Retrieve a list of all known processes. Use the query parameter ids to list (comma separated) the IDs of the process you want to be part of the response. If the list is empty, all processes will be listed. Use the query parameter filter to list (comma separated) the wanted details per process (config, state, log). If the list is empty, all details will be included.
GET	/api/v3/process/:id	Retreive the details of a process including the config, state, and logs. Use the query parameter filter to list (comma separated) the wanted details per process (config, state, log). If the list is empty, all details will be included.
PUT	/api/v3/process/:id	Replaces the process with a new config.
GET	/api/v3/process/:id/config	Retrieve the config of a process as it was provided.
GET	/api/v3/process/:id/state	Retrieve the current state of a process. This includes the progress data if the process is running.
GET	/api/v3/process/:id/report	Retrieve the report and logs of a process.
GET	/api/v3/process/:id/debug	Retrieve an anonymized version of the details of a process.
DELETE	/api/v3/process/:id	Remove a specific process. Only possible if the process is not running.
PUT	/api/v3/process/:id/command	Send a command to a process.
GET	/api/v3/process/:id/data	Get all arbitrary JSON data that is stored with this process.
GET	/api/v3/process/:id/data/:key	Get arbitrary JSON data that is stored under the key key.
PUT	/api/v3/process/:id/data/:key	Store aribtrary JSON data under the key key. If the data is null, the key will be removed.

Commands

A command is defined as:

{
    "command": ("start"|"stop"|"restart"|"reload")
}

Command	Description
start	Start the process. If the process is already started, this won't have any effect.
stop	Stop the process. If the process is already stopped, this won't have any effect.
restart	Restart the process. If the process is not running, this won't have any effect.
reload	Reload the process. If the process was running, the reloaded process will start automatically.

Placeholder

Currently supported placeholders are:

Placeholder	Description	Location
{diskfs}	Will be replaced by the provided CORE_STORAGE_DISK_DIR.	options, input.address, input.options, output.address, output.options
{memfs}	Will be replace by the base URL of the MemFS.	input.address, input.options, output.address, output.options
{processid}	Will be replaced by the ID of the process.	input.id, input.address, input.options, output.id, output.address, output.options, output.cleanup.pattern
{reference}	Will be replaced by the reference of the process	input.id, input.address, input.options, output.id, output.address, output.options, output.cleanup.pattern
{inputid}	Will be replaced by the ID of the input.	input.address, input.options
{outputid}	Will be replaced by the ID of the output.	output.address, output.options, output.cleanup.pattern

Before replacing the placeholder in the process, all references will be resolved, i.e., you can put the placeholder also in the params for an option.

References

The input address of a process may contain a reference to the output of another process. It has the form #[processid]:output=[id].

A reference starts with a # followed by the process ID it refers to, followed by a :. Then comes output, followed by a =. and the ID of the output.

FFmpeg

Statistics

This repository contains a patch for the FFmpeg program to provide detailed progress information. With this patch, FFmpeg will output the progress information in a JSON string that contains the data for each input and output stream individually. The JSON output is enabled by default. It can be enabled with the global -jsonstats switch on the command line. Use the -stats switch on the command line for the standard progress output.

The Docker image that you can build with the provided Dockerfile includes the patched version of FFmpeg for your convenience.

Example output with -stats:

frame=  143 fps= 25 q=-1.0 Lsize=     941kB time=00:00:05.68 bitrate=1357.0kbits/s speed=0.995x

Example output with -jsonstats:

JSONProgress:{"inputs":[{"id":0, "stream":0, "type":"video", "codec":"rawvideo", "coder":"rawvideo", "pix_fmt":"rgb24", "frame":188, "fps":24.95, "width":1280, "height":720, "size_kb":507600, "bitrate_kbps":552960.0},{"id":1, "stream":0, "type":"audio", "codec":"pcm_u8", "coder":"pcm_u8", "frame":314, "sampling_hz":44100, "layout":"stereo", "size_kb":628, "bitrate_kbps":705.6}], "outputs":[{"id":0, "stream":0, "type":"video", "codec":"h264", "coder":"libx264", "pix_fmt":"yuv420p", "frame":188, "fps":24.95, "q":-1.0, "width":1280, "height":720, "size_kb":1247, "bitrate_kbps":1365.6},{"id":0, "stream":1, "type":"audio", "codec":"aac", "coder":"aac", "frame":315, "sampling_hz":44100, "layout":"stereo", "size_kb":2, "bitrate_kbps":2.1}], "frame":188, "fps":24.95, "q":-1.0, "size_kb":1249, "bitrate_kbps":1367.7, "time":"0h0m7.48s", "speed":0.993, "dup":0, "drop":0}

The same output but nicely formatted:

{
    "bitrate_kbps": 1367.7,
    "drop": 0,
    "dup": 0,
    "fps": 24.95,
    "frame": 188,
    "inputs": [
        {
            "bitrate_kbps": 552960.0,
            "codec": "rawvideo",
            "coder": "rawvideo",
            "fps": 24.95,
            "frame": 188,
            "height": 720,
            "id": 0,
            "pix_fmt": "rgb24",
            "size_kb": 507600,
            "stream": 0,
            "type": "video",
            "width": 1280
        },
        {
            "bitrate_kbps": 705.6,
            "codec": "pcm_u8",
            "coder": "pcm_u8",
            "frame": 314,
            "id": 1,
            "layout": "stereo",
            "sampling_hz": 44100,
            "size_kb": 628,
            "stream": 0,
            "type": "audio"
        }
    ],
    "outputs": [
        {
            "bitrate_kbps": 1365.6,
            "codec": "h264",
            "coder": "libx264",
            "fps": 24.95,
            "frame": 188,
            "height": 720,
            "id": 0,
            "pix_fmt": "yuv420p",
            "q": -1.0,
            "size_kb": 1247,
            "stream": 0,
            "type": "video",
            "width": 1280
        },
        {
            "bitrate_kbps": 2.1,
            "codec": "aac",
            "coder": "aac",
            "frame": 315,
            "id": 0,
            "layout": "stereo",
            "sampling_hz": 44100,
            "size_kb": 2,
            "stream": 1,
            "type": "audio"
        }
    ],
    "q": -1.0,
    "size_kb": 1249,
    "speed": 0.993,
    "time": "0h0m7.48s"
}

Resilient Streaming

Prepend the input source with avstream:, e.g. ... -i avstream:rtsp://1.2.3.4/stream.sdp .... It will reconnect to the stream if it breaks and repeats the last known intraframe until new data from the input stream is available.

Example

Start core with the proper environment variables. Create a .env file or provide them on the command line. For this example, please use the following command line:

env CORE_API_AUTH_USERNAME=admin CORE_API_AUTH_PASSWORD=datarhei CORE_LOGLEVEL=debug CORE_STORAGE_DISK_DIR=./data ./core

Also, make sure that the directory ./data exists. Otherwise, the state will not be stored and will be lost after a restart of datarhei/core and the FFmpeg process will not be able to write the files.

In this example, we will add a fake video and audio source. The video will be encoded with H264, and the audio will be encoded with AAC. The output will be an m3u8 stream.

To talk to the API, we use the program httpie.

First, we create a JSON file with the process definition (e.g. testsrc.json):

{
    "id": "testsrc",
    "type": "ffmpeg",
    "options": ["-loglevel", "info", "-err_detect", "ignore_err"],
    "input": [
        {
            "address": "testsrc=size=1280x720:rate=25",
            "id": "video",
            "options": ["-f", "lavfi", "-re"]
        },
        {
            "address": "anullsrc=r=44100:cl=stereo",
            "id": "audio",
            "options": ["-f", "lavfi"]
        }
    ],
    "output": [
        {
            "address": "http://127.0.0.1:8080/memfs/{processid}_{outputid}.m3u8",
            "id": "hls",
            "options": [
                "-codec:v",
                "libx264",
                "-preset:v",
                "ultrafast",
                "-r",
                "25",
                "-g",
                "50",
                "-pix_fmt",
                "yuv420p",
                "-b:v",
                "1024k",
                "-codec:a",
                "aac",
                "-b:a",
                "64k",
                "-hls_time",
                "2",
                "-hls_list_size",
                "10",
                "-hls_flags",
                "delete_segments+temp_file+append_list",
                "-hls_segment_filename",
                "http://127.0.0.1:8080/memfs/{processid}_{outputid}_%04d.ts"
            ]
        }
    ],
    "reconnect": true,
    "reconnect_delay_seconds": 10,
    "stale_timeout_seconds": 10
}

and POST it to the API:

http POST http://localhost:8080/v3/process < testsrc.json

Then check if it is there (as provided)

http http://localhost:8080/v3/process/testsrc

For the advanced, create another JSON file (e.g. dump.json):

{
    "id": "dump",
    "type": "ffmpeg",
    "options": ["-loglevel", "info", "-err_detect", "ignore_err"],
    "input": [
        {
            "address": "#testsrc:output=hls",
            "id": "video",
            "options": []
        }
    ],
    "output": [
        {
            "address": "{diskfs}/{processid}.mp4",
            "id": "hls",
            "options": ["-codec", "copy", "-y"]
        }
    ],
    "reconnect": true,
    "reconnect_delay_seconds": 10,
    "stale_timeout_seconds": 10
}

and POST it to the API:

http POST http://localhost:8080/v3/process < dump.json

Then check if it is there (as provided)

http http://localhost:8080/v3/process/dump

Let's start the testsrc process

http PUT http://localhost:8080/v3/process/testsrc/command command=start

Now we can observe the progress of the process

http http://localhost:8080/v3/process/testsrc

or the log of the process

http http://localhost:8080/v3/process/testsrc/log

If you want to change the video bitrate, edit the testsrc.json file accordingly and replace the process:

http PUT http://localhost:8080/v3/process/testsrc < testsrc.json

It will stop the process, replace the config, and restart it.

Now open, e.g., VLC, and load the stream http://localhost:8080/memfs/testsrc_hls.m3u8.

This is enough; let's stop it

http PUT http://localhost:8080/v3/process/testsrc/command command=stop

and check its progress again

HTTP http://localhost:8080/v3/process/testsrc

Delete the process

HTTP DELETE http://localhost:8080/v3/process/testsrc

Metrics

Metrics for the processes and other aspects are provided for a Prometheus scraper on /metrics.

Currently, available metrics are:

Metric	Type	Dimensions	Description
ffmpeg_process	gauge	core, process, name	General stats per process.
ffmpeg_process_io	gauge	core, process, type, id, index, media, name	Stats per input and output of a process.
mem_limit_bytes	gauge	core	Total available memory in bytes.
mem_free_bytes	gauge	core	Free memory in bytes.
net_rx_bytes	gauge	core, interface	Number of received bytes by interface.
net_tx_bytes	gauge	core, interface	Number of sent bytes by interface.
cpus_system_time_secs	gauge	core, cpu	System time per CPU in seconds.
cpus_user_time_secs	gauge	core, cpu	User time per CPU in seconds.
cpus_idle_time_secs	gauge	core, cpu	Idle time per CPU in seconds.
session_total	counter	core, collector	Total number of sessions by collector.
session_active	gauge	core, collector	Current number of active sessions by collector.
session_rx_bytes	counter	core, collector	Total received bytes by collector.
session_tx_bytes	counter	core, collector	Total sent bytes by collector.

Profiling

Profiling information is available under /profiling. Set the environment variable CORE_DEBUG_PROFILING=true to make this endpoint available. If authentication is enabled, you have to provide the token in the header.

Development

Requirement

• Go v1.16+ (Download here)

Build

Clone the repository and build the binary

git clone git@github.com:datarhei/core.git
cd core
make

After the build process, the binary is available as core

For more build options, run make help.

Cross Compile

If you want to run the binary on a different operating system and/or architecture, you create the appropriate binary by simply setting some environment variables, e.g.

env GOOS=linux GOARCH=arm go build -o core-linux-arm
env GOOS=linux GOARCH=arm64 go build -o core-linux-arm64
env GOOS=freebsd GOARCH=amd64 go build -o core-freebsd-amd64
env GOOS=windows GOARCH=amd64 go build -o core-windows-amd64
env GOOS=macos GOARCH=amd64 go build -o core-macos-amd64
...

Docker

Build the Docker image and run it to try out the API

docker build -t core .
docker run -it --rm -v ${PWD}/data:/core/data -p 8080:8080 core

API Documentation

The documentation of the API is available on /api/swagger/index.html.

To generate the API documentation from the code, use swag.

go install github.com/swaggo/swag (unless already installed)
make swagger

Code style

The source code is formatted with go fmt, or simply run make fmt. Static analysis of the source code is done with staticcheck (see staticcheck), or simply run make lint.

Before committing changes, you should run make commit to ensure that the source code is in shape.

License

datarhei/core is licensed under the Apache License 2.0