Environment variables for the agent

Using environment variables to control agent behavior

The formant user which runs the formant-agent process sources /var/lib/formant/.bashrc before running the agent process. Environment variables can be added to this file to control agent behavior.

What environment variables can I add to /var/lib/formant/.bashrc?

Here is a list of user-facing environment variables, their description, their default values. If the default value is empty, nothing occurs unless the environment variable is set to some value.


Restart the agent for changes to take effect

Please make sure to restart the agent (systemctl restart formant-agent for native installations) for any changes to environment variables to take effect.

ROS environment variables

NameDefault valueDescription
ROS_MASTER_URIhttp://localhost:11311The address of the ROS master to which the Formant ROS Bridge connects.
CATKIN_WSThe path to the root of the catkin workspace. The Formant agent uses this to find custom ROS message definitions.
SOURCE_SCRIPTIf the ROS setup files are not in <catkin_ws>/devel/setup.bash, the custom location of ROS setup script.
FORMANT_AGENT_PYTHON_PATHpythonThe file location of the Python interpreter used by the tf2 bridge.
FORMANT_OVERRIDE_TIMESTAMPfalseEnables replacement of timestamps on ROS messages with the current time.

General environment variables

Default value
FORMANT_AGENT_IPlocalhostThe IP address where the Formant Agent will start it's server.
FORMANT_AGENT_GRPC_UNIX_SOCKET/var/lib/formant/agent.sockThe Unix Socket where the Formant Agent will start it's server.
FORMANT_AGENT_GRPC_PORT5501The port where the Formant Agent will expose the gRPC interface.
FORMANT_AGENT_HTTP_PORT5502The port where the Formant Agent will expose the HTTP interface.
FORMANT_PORT_FORWARDINGtrueEnables the local port forwarding feature.
FORMANT_AGENT_PYTHON3_PATHpython3The file location of the python3 interpreter used by the ROS bridge and media encoder.
FORMANT_DISABLE_PYTHONfalseDisables all python subprocesses for the agent. This includes the media encoder, ROS bridge, and ROS TF bridge. Since the media encoder is a python subprocess, disabling python will disable all video and audio encoding.
FORMANT_DISABLE_TEGRA_STATSfalseDisables the automatic collection and ingestion of default telemetry streams specific to Tegra systems. Jetson products (Nano, Xavier, etc.) are Tegra systems.
FORMANT_DISABLE_STANDARD_HOST_METRICSfalseDisables the automatic collection and ingestion of default telemetry streams, such as CPU, memory, and IP-based location.
FORMANT_DISABLE_TERMINALfalseDisables the web terminal feature that allows users to run a shell through the agent.
FORMANT_AGENT_SERVER_KEYFile location of the TLS key
FORMANT_AGENT_SERVER_CERTFile location of the TLS cert.
FORMANT_DEBUG_OUTPUTfalseEnables debug logs.
FORMANT_UPLOAD_DEBUG_OUTPUTfalseEnables the uploading of debug logs when the environment is not production.
FORMANT_PROVISIONING_TOKENFormant provisioning token used to provision an agent.
FORMANT_NAMEName of the Formant Agent, used to override Agent name during provisioning.
FORMANT_DISABLE_SYSINFOfalseDisables system information collection. (Used for NVIDIA containers).
FORMANT_TERMINAL_BUFFER_SIZE40000Size in bytes of the terminal buffer.
FORMANT_GST_INFOfalseEnable log info for gstreamer

Media environment variables

FORMANT_ACCELERATED_VIDEO_ENCODINGtrueEnables jetson hardware accelerated encoding of video.
FORMANT_FORCE_ACCELERATED_VIDEO_ENCODINGfalseIf the Jetson accelerated encoder crashes, the Formant agent will turn it off. Set this to true to prevent this and keep retrying with acceleration.
FORMANT_ENCODING_BITRATE512Overrides the bitrate (Kbps) of all agent-encoded video streams.
FORMANT_AUDIO_SAMPLE_RATE16000Sample rate of audio device's signal.
FORMANT_AUDIO_NUM_CHANNELS1Number of channels of the audio device.
FORMANT_AUDIO_USE_FILTERtrueUse anlmdn filter on audio to reduce noise.
FORMANT_AUDIO_BITRATE96kDesired bitrate of uploaded audio.
FORMANT_AUDIO_SAMPLE_FORMATs16leSample format of the audio device.
FORMANT_OVERRIDE_AUDIO_CONFIGURATIONfalseOverride audio configuration with provided values.
FORMANT_OVERRIDE_BITRATEfalseOverride video bitrate from configuration.
FORMANT_VIDEO_FRAMERATE24Assumed framerate of video, if framerate cannot be determined from source.
FORMANT_FRAMERATE_CAP30If the hardware source is greater than this value, Formant will re-encode it to this value.
FORMANT_TARGET_FRAMERATE30Target framerate for hardware video streams.
FORMANT_PREFER_H264_SOURCEfalseReceive h264 video directly from hardware camera if offered.
FORMANT_ALLOW_H264_SOURCEfalseIf other pixel formats do not work well, allow H264 to also be chosen. This will be true if FORMANT_PREFER_H264_SOURCE is also true.
FORMANT_PREFER_MJPGfalsePrefer the MJPG hardware video stream, if there is one. Typically, MJPG will be the last choice.
FORMANT_ENABLE_ADAPTIVE_BITRATEtrueAllow Formant to automatically reduce the video bitrate if network degradation is detected during teleoperation. Note: this will also affect encoding for telemetry streams.
FORMANT_LOW_BANDWIDTH_BITRATE64Bitrate to set video to when low bandwidth mode is enabled.
FORMANT_USE_RTP_JITTER_BUFFERfalseEnables use of jitter buffer (debug only).
FORMANT_FLV_DECODEtrueDecode RTMP stream as FLV (Turn off if RTMP stream isn't working, usually because it has an audio stream).
FORMANT_RTSP_BUFFER_LENGTH0Length in ms of RTSP buffer. Increase this to add stability to RTSP video (at cost of latency).
FORMANT_FORCE_ALLOW_PICAMfalseEnable use of Picam on Raspberry Pi or Jetson
FORMANT_DISABLE_RESIZE_VIDEOfalseDisable Formant agent resizing the aspect ratio of the video.
FORMANT_RTSP_PROTOCOLS'"udp+tcp"'Protocol for RTSP stream. Choose udp, tcp or udp+tcp.
FORMANT_ENCODE_SPEED_PRESET"ultrafast"Set the quality/speed tradeoff with GStreamer speed preset (corresponds to the enum GstX264EncPreset).
FORMANT_ACCELERATED_ENCODE_SPEED_PRESET1The speed-preset for Jetson hardware-accelerated video encoding. Values are in the range [0,4].
FORMANT_VIDEO_PASS_OPTIONS0 (or "cbr")Sets the 'rate control' of the video encoder. Corresponds to the enum "GstX264EncPass".

If it is "cbr", "pass1", "pass2", or "pass3", then the bitrate that is specified (either by FORMANT_OVERRIDE_BITRATE or by Formant) will be the target bitrate. See this page for more details.
FORMANT_VIDEO_QUANTIZER21If using "quant" (4) or "qual" (5) above, then this will be the parameter passed to the quantizer. See the documentation here for more details.