Refactor: Modular architecture with pluggable balancers and config support#7
Merged
andrescera merged 13 commits intomainfrom Jan 10, 2026
Merged
Conversation
- Create bitrate_control.h with BitrateContext struct and public API - Create bitrate_control.c with algorithm implementation - Move all bitrate-related constants to named #defines in header - Refactor belacoder.c to use BitrateContext for state management - Update Makefile to compile new module This is the first step in modularizing the codebase as outlined in Issue #2. The bitrate algorithm logic is now testable in isolation and the main file is reduced from 915 to 785 lines. No functional changes - algorithm behavior is identical.
- Add bitrate_control.c/h to repository structure - Add Module Overview table showing file responsibilities - Update Key Abstractions table with file locations - Document BitrateContext struct and API in bitrate-control.md - Note that module structure enables future algorithm swapping
Preserve original BELABOX attribution while adding CERALIVE as additional copyright holder for 2026 contributions.
Introduces a pluggable architecture for bitrate control algorithms: New files: - balancer.h: BalancerAlgorithm interface with init/step/cleanup - balancer_adaptive.c: Wraps existing RTT+buffer algorithm as 'adaptive' - balancer_registry.c: Algorithm registry and lookup functions Changes to belacoder.c: - Add -a <algorithm> CLI flag for algorithm selection - Use balancer interface instead of direct BitrateContext - Print available algorithms in help text - Default to 'adaptive' when no flag specified (preserves existing behavior) The 'adaptive' algorithm is the default and provides identical behavior to the previous implementation. This lays the groundwork for adding alternative algorithms (fixed, aimd, latency_target) in Phase 2. Addresses Issue #3: Multi-Algorithm Bitrate Control Support
New balancer algorithms: 1. 'fixed' - Constant bitrate with no adaptation - Outputs max_bitrate constantly - Useful for testing or stable networks 2. 'aimd' - Additive Increase Multiplicative Decrease - Classic TCP-style congestion control - Linear increase (+50 Kbps) when stable - Multiplicative decrease (75%) on congestion - Provides fair bandwidth sharing Usage: ./belacoder -a fixed pipeline.txt host 4000 ./belacoder -a aimd pipeline.txt host 4000 Both algorithms integrate with the balancer interface from Phase 1. The 'adaptive' algorithm remains the default. Continues work on Issue #3: Multi-Algorithm Bitrate Control Support
Enhances the adaptive balancer with packet loss as a congestion signal: - Add pkt_loss_total and pkt_retrans_total to BalancerInput - Track packet loss rate with EMA smoothing in BitrateContext - Trigger heavy congestion decrease when loss_rate > 0.5 packets/interval - Block bitrate increase while experiencing packet loss This makes the adaptive algorithm more responsive to network issues, especially on mobile networks where packet loss often precedes RTT increases. SRT stats used: - pktSndLossTotal: Cumulative packets reported lost - pktRetransTotal: Cumulative packets retransmitted
- Add config.h/config.c for INI-style config parser - Support -c <config> CLI option - Config file uses Kbps units (500 = 500 Kbps, 6000 = 6 Mbps) - SIGHUP reloads full config (not just bitrate file) - CLI flags override config values (-a overrides balancer=) - Include belacoder.conf.example with all options documented - Update .gitignore to ignore all .o files
- Add Kbps unit examples (500 = 500 Kbps, 6000 = 6 Mbps) - Document balancer algorithm options - Explain SRT latency purpose and typical values - Mark algorithm tuning sections as future/not yet implemented - Comment out unused sections to avoid confusion
- stream_id was parsed from config but never applied - Now g_config.stream_id is used if set and -s flag not provided - CLI -s flag still overrides config value
stream_id rarely changes, keep it as -s flag only
- Add adaptive/aimd tuning params to BalancerConfig - Pass config values from belacoder.c to each algorithm - Adaptive: configurable incr_step, decr_step, intervals - AIMD: configurable incr_step, decr_mult, intervals - Update bitrate_context_init to accept tuning params - Use ctx fields instead of hardcoded defines in bitrate_update - Update documentation (architecture.md, bitrate-control.md) - Config file [adaptive] and [aimd] sections now functional
- Move all .c and .h files to src/ - Update Makefile for new structure - Update documentation (architecture.md, bitrate-control.md) - Cleaner root directory with only config files and docs
- Reorganize src/ into core/, io/, net/, gst/ subdirectories - Extract modules: cli_options, pipeline_loader, srt_client, encoder_control, overlay_ui, balancer_runner - Add cmocka integration tests (16 tests covering balancer algorithms, config handling, bounds, edge cases) - Update Makefile with new paths and test targets - Update documentation with new structure The modular structure improves maintainability and testability while preserving all existing functionality.
This was referenced Jan 10, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR refactors belacoder into a modular, testable architecture while adding significant new features:
New Features
Architecture Changes
src/into subdirectories:core/- config, balancer algorithms, runnerio/- CLI options, pipeline loadernet/- SRT clientgst/- encoder control, overlay UItests/directory with cmocka integration testsModule Overview
src/io/cli_options.c/hsrc/core/config.c/hsrc/net/srt_client.c/hsrc/gst/encoder_control.c/hsrc/core/balancer_runner.c/hTest Coverage
Test plan
makebuilds without warningsmake testpasses all 16 testskill -HUP