How to Configure Video Bitrate and Frame Rate Settings for Main and Sub Streams in AtomCam Tools

Use the /scripts/cmd video bitrate and /scripts/cmd video fps commands to adjust stream quality dynamically, or set the BITRATE_* and FRAMERATE keys in hack.ini for persistent configuration.

The atomcam_tools firmware enhancement for Wyze and Atom cameras exposes low-level video encoder controls that allow precise tuning of network bandwidth and motion smoothness. By manipulating the bitrate and frame rate parameters for the Main (HD) and Sub (360p/320p) streams, you can optimize video quality to match your storage constraints and network upload capacity.

Understanding Video Stream Channels

The camera firmware manages three distinct encoder channels that map to specific stream types:

• Channel 0: Main stream (HD, AVC/H.264) – typically 300–2000 kbps, default 960 kbps
• Channel 1: Sub stream (360p/320p, HEVC/H.265) – typically 100–500 kbps, default 180 kbps
• Channel 3: Main stream alternative (HD, HEVC/H.265) – typically 300–2000 kbps, default 800 kbps

According to the source code in libcallback/video_control.c, the global frame rate (1–30 fps, default ~25 fps) applies to all channels simultaneously rather than individual streams.

Configuring Video Bitrate

Runtime Configuration via Command Line

For immediate changes that persist until reboot, use the video bitrate command followed by the channel number and target bitrate in kbps:

# Set Main AVC stream (channel 0) to 1200 kbps

/scripts/cmd video bitrate 0 1200

# Set Sub HEVC stream (channel 1) to 300 kbps

/scripts/cmd video bitrate 1 300

# Reset Main HEVC stream (channel 3) to application default

/scripts/cmd video bitrate 3 auto

The command invokes the Bitrate() function in /libcallback/video_control.c (lines 166–176), which validates the input range (10–3000 kbps) before applying the change to the encoder SDK.

Persistent Configuration via hack.ini

To maintain settings across reboots, edit the hack.ini file located at /tmp/hack.ini or on the SD card root:

BITRATE_MAIN_AVC=1500
BITRATE_SUB_HEVC=300
BITRATE_MAIN_HEVC=1800

During boot, /overlay_rootfs/scripts/set_icamera_config.sh (lines 45–51) reads these values and invokes the same command-line utilities to initialize the encoder.

Web UI Configuration

The web interface at http://atomcam.local sends commands through /overlay_rootfs/scripts/webcmd.sh (lines 51–58). Selecting bitrate options triggers the underlying /scripts/cmd video bitrate utility with the appropriate channel parameters.

Configuring Frame Rate

The frame rate setting affects all video channels globally and must be within the 1–30 fps range.

Command Line Adjustment

Execute the video fps command to change the encoder frame rate immediately:

# Set global frame rate to 25 fps

/scripts/cmd video fps 25

This calls the Framerate() function in libcallback/video_control.c (lines 167–176), which validates that the value falls between 1 and 30 fps before reconfiguring the encoder timing.

Persistent Frame Rate Settings

Add the following to your hack.ini configuration:

FRAMERATE=25

The boot script set_icamera_config.sh applies this value during system initialization, ensuring consistent motion characteristics across all streams.

Technical Implementation Details

The configuration system relies on three critical components in the mnakada/atomcam_tools repository:

• /libcallback/video_control.c: Contains the Bitrate() and Framerate() parsing functions that validate input ranges and interface with local_sdk_video_stop/start to restart encoder channels when parameters change.
• /overlay_rootfs/scripts/set_icamera_config.sh: Parses hack.ini at boot time and translates configuration keys into executable commands.
• /overlay_rootfs/scripts/webcmd.sh: Acts as a bridge between the HTTP web interface and the command-line utilities.

When you modify bitrate or frame rate, the firmware executes a stop-start sequence on the affected encoder channels (0, 1, and 3), causing a brief video interruption while the new parameters take effect.

Important Considerations

Validation Limits: The Bitrate() function rejects values below 10 kbps or above 3000 kbps, while Framerate() enforces a 1–30 fps boundary. Invalid inputs return an "error" response without modifying the encoder.

Auto Reset: Specifying auto for any bitrate channel clears the user override (userBitrate[ch]=0) and restores the application default (appBitrate[ch]) defined by the firmware.

Encoder Restart: Every bitrate or frame rate change triggers a restart of the video encoder channels. Expect a momentary stream interruption when applying new settings.

Summary

• Use /scripts/cmd video bitrate <channel> <kbps> for immediate bitrate changes on channels 0 (Main AVC), 1 (Sub HEVC), or 3 (Main HEVC).
• Use /scripts/cmd video fps <value> to set the global frame rate between 1–30 fps.
• Configure BITRATE_MAIN_AVC, BITRATE_SUB_HEVC, BITRATE_MAIN_HEVC, and FRAMERATE in hack.ini for persistent boot-time settings.
• All changes restart the encoder channels briefly; valid ranges are enforced by video_control.c.
• The web UI, command line, and configuration file all interface with the same underlying SDK functions.

Frequently Asked Questions

What are the valid bitrate ranges for each stream?

According to the atomcam_tools README and source validation in video_control.c, Main streams (channels 0 and 3) support 300–2000 kbps, while the Sub stream (channel 1) typically operates between 100–500 kbps. The absolute technical limits enforced by the firmware are 10–3000 kbps.

Why does my video stream briefly cut out when changing settings?

The local_sdk_video_stop/start sequence in video_control.c (lines 60–70) restarts the encoder channels to apply new timing and compression parameters. This architectural requirement ensures clean initialization of the hardware encoder but causes a momentary interruption.

Can I set different frame rates for Main and Sub streams?

No. The frame rate is a global encoder setting that applies to all channels simultaneously. The Framerate() function in video_control.c configures the base timing for the entire video subsystem rather than individual streams.

What happens if I specify a bitrate outside the allowed range?

The Bitrate() function returns an "error" string and ignores the command if the value is less than 10 kbps or greater than 3000 kbps. Similarly, Framerate() rejects values outside the 1–30 fps range. You must specify values within these boundaries for the settings to take effect.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}