Skip to main content
Version: 2026.05.1

Media processing

Phonexia media-processing is a tool for audio media manipulation. It converts audio streams to a consistent format and lets you split, keep, or mix channels, as well as merge multiple audio streams into a single multichannel output. To learn more about the technology, visit this link.

Installation​

Getting the image​

You can easily obtain the media processing image from docker hub.

You can get the image by specifying a direct version in the tag (e.g. 1.0.0) or latest for the latest image:

docker pull phonexia/media-processing:latest

Running the image​

You can start the microservice and list all the supported options by running:

docker run --rm -it phonexia/media-processing:latest --help

The output should look like this:

media_processing 2.0.0 


media_processing [OPTIONS]


OPTIONS:
  -h,     --help              Print this help message and exit 
          --version           Display program version information and exit 
  -a,     --listening_address address [[::]]  (Env:PHX_LISTENING_ADDRESS) 
                              Address on which the server will be listening. Address '[::]' 
                              also accepts IPv4 connections. 
  -p,     --port number [8080]  (Env:PHX_PORT) 
                              Port on which the server will be listening. 
  -l,     --log_level level:{error,warning,info,debug,trace} [info]  (Env:PHX_LOG_LEVEL) 
                              Logging level. Possible values: error, warning, info, debug, 
                              trace. 
          --keepalive_time_s number:[0, max_int] [60]  (Env:PHX_KEEPALIVE_TIME_S) 
                              Time between 2 consecutive keep-alive messages, that are sent if 
                              there is no activity from the client. If set to 0, the default 
                              gRPC configuration (2hr) will be set (note, that this may get the 
                              microservice into unresponsive state). 
          --keepalive_timeout_s number:[1, max int] [20]  (Env:PHX_KEEPALIVE_TIMEOUT_S) 
                              Time to wait for keep alive acknowledgement until the connection 
                              is dropped by the server. 
          --num_instances_per_device NUM:UINT > 0 (Env:PHX_NUM_INSTANCES_PER_DEVICE) 
                              Number of instances per device. Microservice can process requests 
                              concurrently if value is >1. 
          --max_audio_length FLOAT:NONNEGATIVE [0]  (Env:PHX_MAX_AUDIO_LENGTH) 
                              Maximum length of input audio in seconds. 0 means no limit.

You can specify the options either via command line arguments or via environmental variables.

Run the container with the parameters:

docker run --rm -it -p 8080:8080 phonexia/media-processing:latest

With this command, the container will start, and the microservice will be listening on port 8080 on localhost.

Performance optimization​

The media-processing microservice performs media conversion and stream merging. It relies on FFmpeg for audio processing.

Microservice communication​

gRPC API​

For communication, our microservices use gRPC, which is a high-performance, open-source Remote Procedure Call (RPC) framework that enables efficient communication between distributed systems using a variety of programming languages. We use an interface definition language to specify a common interface and contracts between components. This is primarily achieved by specifying methods with parameters and return types.

Take a look at our gRPC API documentation. The media-processing microservice defines a MediaProcessing service with remote procedures called Convert and Merge.

Convert accepts a stream of ConvertRequest messages that include the audio bytes and a conversion configuration. The config controls the channel mode (MIX, SPLIT, or KEEP) and optional channel list. The audio is streamed to the server, and the server responds with a stream of ConvertResponse messages that contain the converted audio and a tag describing which output stream it belongs to.

Merge accepts a stream of MergeRequest messages. Each input stream is identified by a numeric tag, and audio data for a tag must be sent contiguously before switching to another tag. The server replies with a stream of MergeResponse messages containing the merged multichannel audio.

Connecting to microservice​

There are multiple ways how you can communicate with our microservices.

Phonexia Python client​

The easiest way to get started with testing is to use our simple Python client. To get it, run:

pip install phonexia-media-processing-client

After the successful installation, run the following command to see the client options:

media_processing_client --help

Versioning​

We use Semantic Versioning.