Add runtime filler-mode toggle via /api/filler-mode

Wraps the active FillerMode in a thread-safe FillerModeState the PCM reader
polls each chunk, so a host app can flip between silence and an audible test
tone at runtime without restarting the process. Lets a manually-triggered
test recording capture a verifiable tone instead of encoded digital zero
whenever no real PCM is flowing.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: dsward2

Sources/LiveAudioServerCore/HTTPServer.swift

@@ -491,6 +491,7 @@ final class HTTPConnection {
     private let nowPlayingStore: NowPlayingStore
     private let mp3Recorder: FileRecorder?
     private let aacRecorder: FileRecorder?
+    private let fillerModeState: FillerModeState
     private let onClose: (() -> Void)?
     private var receiveBuffer = Data()
     private var clientID: UUID?
@@ -505,6 +506,7 @@ final class HTTPConnection {
          nowPlayingStore: NowPlayingStore,
          mp3Recorder: FileRecorder?,
          aacRecorder: FileRecorder?,
+         fillerModeState: FillerModeState,
          onClose: (() -> Void)? = nil) {
         self.connection      = connection
         self.config          = config
@@ -515,6 +517,7 @@ final class HTTPConnection {
         self.nowPlayingStore = nowPlayingStore
         self.mp3Recorder     = mp3Recorder
         self.aacRecorder     = aacRecorder
+        self.fillerModeState = fillerModeState
         self.onClose         = onClose
     }
 
@@ -623,6 +626,9 @@ final class HTTPConnection {
         case ("POST", "/api/now-playing"):
             serveNowPlayingPost(body: body)
             return
+        case ("POST", "/api/filler-mode"):
+            serveFillerModePost(body: body)
+            return
         default:
             break
         }
@@ -653,6 +659,8 @@ final class HTTPConnection {
             serveNowPlayingGet(headOnly: method == "HEAD")
         case "/api/recorder":
             serveRecorderStatus(headOnly: method == "HEAD")
+        case "/api/filler-mode":
+            serveFillerModeStatus(headOnly: method == "HEAD")
         default:
             if config.enableHLS,
                let segmenter = hlsSegmenter,
@@ -908,6 +916,29 @@ final class HTTPConnection {
         sendJSONResponse(recorderStatusEnvelope())
     }
 
+    // MARK: - Filler Mode API
+
+    private struct FillerModeBody: Codable { let mode: String }
+    private struct FillerModeStatus: Codable { let mode: String }
+
+    private func serveFillerModeStatus(headOnly: Bool) {
+        sendJSONResponse(FillerModeStatus(mode: fillerModeState.mode.rawValue), headOnly: headOnly)
+    }
+
+    /// Switches the live filler mode (silence ⟷ tone) without restarting the
+    /// process — see `FillerModeState`. Lets a host app (e.g. a "start a test
+    /// recording" button) get an audible confirmation tone recorded even when
+    /// no real PCM is flowing, then switch back to silence afterward.
+    private func serveFillerModePost(body: Data) {
+        guard let req = try? JSONDecoder().decode(FillerModeBody.self, from: body),
+              let newMode = FillerMode(cliArgument: req.mode) else {
+            sendStatus(400, "Bad Request")
+            return
+        }
+        fillerModeState.mode = newMode
+        sendJSONResponse(FillerModeStatus(mode: newMode.rawValue))
+    }
+
     private func serveHLSPlaylist(headOnly: Bool) {
         guard let segmenter = hlsSegmenter else {
             connection.send(content: notFoundResponse(), completion: .contentProcessed { [weak self] _ in
@@ -962,6 +993,7 @@ final class HTTPServer {
     private let nowPlayingStore: NowPlayingStore
     private let mp3Recorder: FileRecorder?
     private let aacRecorder: FileRecorder?
+    private let fillerModeState: FillerModeState
     private let tlsIdentity: sec_identity_t?
     private var startedAt = Date()
     private var httpListener: NWListener?
@@ -976,6 +1008,7 @@ final class HTTPServer {
          nowPlayingStore: NowPlayingStore,
          mp3Recorder: FileRecorder?,
          aacRecorder: FileRecorder?,
+         fillerModeState: FillerModeState,
          tlsIdentity: sec_identity_t? = nil) {
         self.config          = config
         self.mp3Broadcaster  = mp3Broadcaster
@@ -984,6 +1017,7 @@ final class HTTPServer {
         self.nowPlayingStore = nowPlayingStore
         self.mp3Recorder     = mp3Recorder
         self.aacRecorder     = aacRecorder
+        self.fillerModeState = fillerModeState
         self.tlsIdentity     = tlsIdentity
     }
 
@@ -1099,6 +1133,7 @@ final class HTTPServer {
                                          nowPlayingStore: self.nowPlayingStore,
                                          mp3Recorder: self.mp3Recorder,
                                          aacRecorder: self.aacRecorder,
+                                         fillerModeState: self.fillerModeState,
                                          onClose: { [weak self] in
                                              self?.connectionLock.lock()
                                              self?.activeConnections.removeValue(forKey: id)

Sources/LiveAudioServerCore/LiveAudioServer.swift

@@ -82,6 +82,9 @@ public final class LiveAudioServer: @unchecked Sendable {
     private var pcmReader: PCMReader?
     private var readerThread: Thread?
     private var statsTimer: DispatchSourceTimer?
+    /// Runtime-mutable filler mode, toggleable via `/api/filler-mode` without
+    /// restarting the process. Seeded from `config.fillerMode` on each start.
+    private var fillerModeState: FillerModeState?
 
     public init(config: ServerConfig) {
         self.config = config
@@ -208,13 +211,17 @@ public final class LiveAudioServer: @unchecked Sendable {
         let nowPlayingStore = NowPlayingStore()
         self.nowPlayingStore = nowPlayingStore
 
+        let fillerModeState = FillerModeState(config.fillerMode)
+        self.fillerModeState = fillerModeState
+
         let httpServer = HTTPServer(config: config,
                                     mp3Broadcaster: mp3Broadcaster,
                                     m4aBroadcaster: m4aBroadcaster,
                                     hlsSegmenter: hlsSegmenter,
                                     nowPlayingStore: nowPlayingStore,
                                     mp3Recorder: mp3Recorder,
                                     aacRecorder: aacRecorder,
+                                    fillerModeState: fillerModeState,
                                     tlsIdentity: tlsIdentity)
         do {
             try httpServer.start()
@@ -232,7 +239,7 @@ public final class LiveAudioServer: @unchecked Sendable {
         }
         self.bonjourPublisher = bonjourPublisher
 
-        let pcmReader = PCMReader(config: config, broadcaster: pcmBroadcaster)
+        let pcmReader = PCMReader(config: config, broadcaster: pcmBroadcaster, fillerModeState: fillerModeState)
         self.pcmReader = pcmReader
 
         // SIGPIPE: prevent the process from dying when a client disconnects
@@ -323,5 +330,6 @@ public final class LiveAudioServer: @unchecked Sendable {
         bonjourPublisher = nil
         pcmReader        = nil
         readerThread     = nil
+        fillerModeState  = nil
     }
 }

Sources/LiveAudioServerCore/PCMSource.swift

@@ -151,13 +151,35 @@ struct FillerGenerator {
     }
 }
 
+// MARK: - Filler Mode State
+
+/// Thread-safe box around the active `FillerMode`, mutable at runtime via the
+/// `/api/filler-mode` HTTP endpoint (see `HTTPServer`). The PCM reader polls
+/// this each time it needs to (re)build its `FillerGenerator`, so a toggle
+/// takes effect on the next chunk without restarting the server — letting a
+/// host app switch a live process between silence and an audible test tone.
+final class FillerModeState: @unchecked Sendable {
+    private let lock = NSLock()
+    private var _mode: FillerMode
+
+    init(_ mode: FillerMode) {
+        self._mode = mode
+    }
+
+    var mode: FillerMode {
+        get { lock.lock(); defer { lock.unlock() }; return _mode }
+        set { lock.lock(); _mode = newValue; lock.unlock() }
+    }
+}
+
 // MARK: - PCM Reader
 
 /// Continuously reads raw 16-bit little-endian interleaved PCM from stdin, UDP,
 /// or TCP and broadcasts frames to all registered consumers.
 final class PCMReader: @unchecked Sendable {
     private let config: ServerConfig
     private let broadcaster: PCMBroadcaster
+    private let fillerModeState: FillerModeState
     private var isRunning = false
     /// Set by `stop()` to break out of every loop unconditionally. Distinct
     /// from `isRunning` so we can tell "natural EOF" (isRunning flipped by
@@ -170,9 +192,20 @@ final class PCMReader: @unchecked Sendable {
     /// stream. Reset to zero whenever any non-zero sample is encountered.
     private var consecutiveZeroSamples: Int = 0
 
-    init(config: ServerConfig, broadcaster: PCMBroadcaster) {
+    init(config: ServerConfig, broadcaster: PCMBroadcaster, fillerModeState: FillerModeState) {
         self.config = config
         self.broadcaster = broadcaster
+        self.fillerModeState = fillerModeState
+    }
+
+    /// Rebuilds `generator` in place if the live filler mode has changed since
+    /// it was created, so a runtime `/api/filler-mode` toggle takes effect on
+    /// the very next chunk. Losing phase continuity across a mode switch is a
+    /// one-chunk click at worst — acceptable for a state that changes rarely.
+    private func refreshFillerGeneratorIfNeeded(_ generator: inout FillerGenerator) {
+        guard generator.mode != fillerModeState.mode else { return }
+        generator = FillerGenerator(mode: fillerModeState.mode, channels: config.channels,
+                                     sampleRate: config.sampleRate, toneHz: config.fillerToneHz)
     }
 
     /// Blocks the calling thread — run on a dedicated background thread.
@@ -268,7 +301,7 @@ final class PCMReader: @unchecked Sendable {
     private func runSilenceFill() {
         let chunkBytes = config.stdinChunkBytes
         var fillerBuf  = [UInt8](repeating: 0, count: chunkBytes)
-        var generator  = FillerGenerator(mode: config.fillerMode,
+        var generator  = FillerGenerator(mode: fillerModeState.mode,
                                          channels: config.channels,
                                          sampleRate: config.sampleRate,
                                          toneHz: config.fillerToneHz)
@@ -285,6 +318,7 @@ final class PCMReader: @unchecked Sendable {
         }
 
         while !shutdownRequested {
+            refreshFillerGeneratorIfNeeded(&generator)
             generator.fillChunk(&fillerBuf)
             broadcastPCMBytes(fillerBuf)
             usleep(chunkPeriodUSec)
@@ -373,7 +407,7 @@ final class PCMReader: @unchecked Sendable {
         var readBuf = [UInt8](repeating: 0, count: max(chunkBytes, 65536))
         var pending = [UInt8]()
 
-        var fillerGen = FillerGenerator(mode: config.fillerMode,
+        var fillerGen = FillerGenerator(mode: fillerModeState.mode,
                                         channels: config.channels,
                                         sampleRate: config.sampleRate,
                                         toneHz: config.fillerToneHz)
@@ -396,9 +430,10 @@ final class PCMReader: @unchecked Sendable {
                     consecutiveTimeouts += 1
                     if consecutiveTimeouts >= timeoutsBeforeFiller {
                         if !fillerActive {
-                            log("UDP input idle — emitting \(config.fillerMode) filler until traffic resumes")
+                            log("UDP input idle — emitting \(fillerModeState.mode) filler until traffic resumes")
                             fillerActive = true
                         }
+                        refreshFillerGeneratorIfNeeded(&fillerGen)
                         fillerGen.fillChunk(&fillerBuf)
                         broadcastPCMBytes(fillerBuf)
                     }
@@ -452,7 +487,7 @@ final class PCMReader: @unchecked Sendable {
         var readBuf    = [UInt8](repeating: 0, count: max(chunkBytes, 8192))
         var pending    = [UInt8]()
 
-        var fillerGen = FillerGenerator(mode: config.fillerMode,
+        var fillerGen = FillerGenerator(mode: fillerModeState.mode,
                                         channels: config.channels,
                                         sampleRate: config.sampleRate,
                                         toneHz: config.fillerToneHz)
@@ -478,9 +513,10 @@ final class PCMReader: @unchecked Sendable {
                     consecutiveTimeouts += 1
                     if consecutiveTimeouts >= timeoutsBeforeFiller {
                         if !fillerActive {
-                            log("TCP input idle — emitting \(config.fillerMode) filler until traffic resumes")
+                            log("TCP input idle — emitting \(fillerModeState.mode) filler until traffic resumes")
                             fillerActive = true
                         }
+                        refreshFillerGeneratorIfNeeded(&fillerGen)
                         fillerGen.fillChunk(&fillerBuf)
                         broadcastPCMBytes(fillerBuf)
                     }