Phase 0: Add backend infrastructure tracking

[Copilot]

Summary

Adds minimal infrastructure for multi-backend fallback support. Tracks active backends (capture, encoder, audio, display, decoder) and displays status on startup. No behavioral changes—pure foundation for Phases 1-6.

Details

• New feature
• Bug fix
• Performance improvement
• Documentation / tooling

What changed?

Header (include/rootstream.h)

• Added active_backend struct tracking 6 backend types (capture, encoder, audio cap/play, decoder, display)
• Added backend_prefs struct for override options and verbose mode
• Added TRY_INIT_BACKEND macro for future fallback selection (unused in Phase 0)

Core init (src/core.c)

• Initialize all backend fields to "uninitialized"
• Set backend_prefs defaults

CLI (src/main.c)

• Added --backend-verbose flag (plumbing for future phases)

Service layer (src/service.c)

• Set active_backend fields after successful initialization
• Display backend status box before main loops:

╔════════════════════════════════════════════════╗
║  RootStream Backend Status                     ║
╚════════════════════════════════════════════════╝
Capture:       DRM/KMS
Encoder:       NVENC (NVIDIA GPU)
Audio Cap:     ALSA
Audio Play:    disabled

Rationale

Current fallback chains (DRM→X11→Dummy, NVENC→VA-API→FFmpeg→Raw) lack visibility. Users don't know which backend initialized. This adds zero-cost tracking (string pointers) and startup reporting, enabling:

• Immediate troubleshooting visibility
• Foundation for future override flags (--encoder=ffmpeg)
• Cleaner fallback addition in later phases

Aligns with simplicity: no abstractions, just tracking what already exists.

Testing

• Built successfully (syntax validation on all modified files)
• Struct field access verified with test program
• TRY_INIT_BACKEND macro compiles correctly
• CodeQL security scan passed

Runtime testing requires full dependency chain (libsodium, SDL2, VA-API, etc.) not available in CI. Manual testing:

• Host mode displays capture/encoder/audio backend status
• Client mode displays decoder/display/audio backend status
• --backend-verbose flag accepted

Notes

• Latency impact: None. Tracking is string pointers set once at init.
• Follow-up: Phases 1-6 will populate fallback chains using this infrastructure.
• Decoder naming: Platform-based (VA-API/Media Foundation). Future phases could add runtime detection.
• TRY_INIT_BACKEND macro: Reserved for future phases, documented with usage examples.

Original prompt

PHASE 0: Backend Infrastructure Setup (Simplified)

Goal

Create the foundation for multi-fallback support by adding backend abstraction to the codebase. This is NOT a massive refactor—just the minimal infrastructure needed so Phases 1-6 can add fallback implementations cleanly.

Current State

• Main loops exist in service_run_host() and service_run_client()
• Each subsystem initializes with hard-coded function calls
• No mechanism for fallback selection
• No runtime reporting of which backend is active

Solution: Three Small Changes

Change 1: Add Backend Tracking to Context

In include/rootstream.h, find typedef struct rootstream_ctx_t and add:

/* Backend tracking (added in PHASE 0) */
struct {
    const char *capture_name;      /* Name of active capture backend */
    const char *encoder_name;      /* Name of active encoder backend */
    const char *audio_cap_name;    /* Name of active audio capture backend */
    const char *audio_play_name;   /* Name of active audio playback backend */
} active_backend;

/* User preferences for backend override */
struct {
    const char *capture_override;  /* User-specified capture backend */
    const char *encoder_override;  /* User-specified encoder backend */
    bool verbose;                  /* Print fallback attempts */
} backend_prefs;

Change 2: Add Simple Fallback Selection Macro

In include/rootstream.h, add:

/* Simple fallback selection macro */
#define TRY_INIT_BACKEND(ctx, primary_fn, primary_name, fallback_fn, fallback_name, result_ptr, name_ptr) \
    do { \
        if ((primary_fn)(ctx) == 0) { \
            (name_ptr) = (primary_name); \
            (result_ptr) = 1; /* Mark as initialized */ \
        } else if ((fallback_fn) && (fallback_fn)(ctx) == 0) { \
            printf("INFO: Primary failed, using fallback: %s\n", (fallback_name)); \
            (name_ptr) = (fallback_name); \
            (result_ptr) = 1; \
        } else { \
            printf("ERROR: Both primary and fallback failed\n"); \
            (result_ptr) = 0; \
        } \
    } while(0)

Change 3: Add Feature Detection to Context Init

In src/core.c, in the rootstream_init() function, add (near the end before return 0):

/* Initialize backend tracking (PHASE 0) */
ctx->active_backend.capture_name = "uninitialized";
ctx->active_backend.encoder_name = "uninitialized";
ctx->active_backend.audio_cap_name = "uninitialized";
ctx->active_backend.audio_play_name = "uninitialized";

ctx->backend_prefs.capture_override = NULL;
ctx->backend_prefs.encoder_override = NULL;
ctx->backend_prefs.verbose = false;

printf("INFO: Backend infrastructure initialized\n");

Change 4: Add CLI Option for Backend Verbose Mode

In src/main.c, in the option parsing section, add:

/* Add to long_options array */
{"backend-verbose", no_argument, 0, 0},

/* In option parsing loop */
if (strcmp(long_options[option_index].name, "backend-verbose") == 0) {
    ctx->backend_prefs.verbose = true;
    printf("INFO: Backend selection verbose mode enabled\n");
}

Change 5: Update Service Startup Report

In src/service.c, in service_run_host(), after all initialization is complete (before main loop), add:

/* Report active backends (PHASE 0) */
printf("\n");
printf("╔════════════════════════════════════════════════╗\n");
printf("║  RootStream Backend Status                     ║\n");
printf("╚════════════════════════════════════════════════╝\n");
printf("Capture:       %s\n", ctx->active_backend.capture_name);
printf("Encoder:       %s\n", ctx->active_backend.encoder_name);
printf("Audio Cap:     %s\n", ctx->active_backend.audio_cap_name ? ctx->active_backend.audio_cap_name : "disabled");
printf("Audio Play:    %s\n", ctx->active_backend.audio_play_name ? ctx->active_backend.audio_play_name : "disabled");
printf("\n");

And similar in service_run_client():

printf("\n");
printf("╔════════════════════════════════════════════════╗\n");
printf("║  RootStream Client Backend Status              ║\n");
printf("╚════════════════════════════════════════════════╝\n");
printf("Decoder:       %s\n", ctx->active_backend.decoder_name ? ctx->active_backend.decoder_name : "uninitialized");
printf("Display:       %s\n", "SDL2");  /* Hardcoded for now */
printf("Audio Play:    %s\n", ctx->active_backend.audio_play_name ? ctx->active_backend.audio_play_name : "disabled");
printf("\n");

Implementation Steps

1. Edit include/rootstream.h:

   • Add active_backend struct to rootstream_ctx_t
   • Add backend_prefs struct to rootstream_ctx_t
   • Add TRY_INIT_BACKEND macro

2. Edit src/core.c:

   • Initialize backend tracking in rootstream_init()

3. Edit src/main.c:

   • Add --backend-verbose CLI option

4. Edit src/service.c:

   • Update service_run_host() to set ctx->active_backend.capture_name after init
   • Update service_run_host() to set ctx->active_backend.encoder_name after ...

This pull request was created from Copilot chat.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.