docs: mic meter demo (#64)

* feat: scaffold audio waveform demo [WIP]

* fix: prevent newlines from creating empty log events

* test: cover empty events from processing newlines

* fix: handle audio output chunks

* feat: finish mic meter demo

* refactor: rename example "terminal" => "terminal_video"

* fix: typo in doc comment

Author: nathanbabcock

examples/mic_meter.rs

@@ -0,0 +1,101 @@
+use anyhow::{Context, Result};
+use ffmpeg_sidecar::{
+  command::FfmpegCommand,
+  event::{FfmpegEvent, LogLevel},
+};
+use std::{cmp::max, iter::repeat};
+
+/// Process microphone audio data in realtime and display a volume meter/level
+/// indicator rendered to the terminal.
+pub fn main() -> Result<()> {
+  if cfg!(not(windows)) {
+    eprintln!("Note: Methods for capturing audio are platform-specific and this demo is intended for Windows.");
+    eprintln!("On Linux or Mac, you need to switch from the `dshow` format to a different one supported on your platform.");
+    eprintln!("Make sure to also include format-specific arguments such as `-audio_buffer_size`.");
+    eprintln!("Pull requests are welcome to make this demo cross-platform!");
+  }
+
+  // First step: find default audio input device
+  // Runs an `ffmpeg -list_devices` command and selects the first one found
+  // Sample log output: [dshow @ 000001c9babdb000] "Headset Microphone (Arctis 7 Chat)" (audio)
+
+  let audio_device = FfmpegCommand::new()
+    .hide_banner()
+    .args(&["-list_devices", "true"])
+    .format("dshow")
+    .input("dummy")
+    .spawn()?
+    .iter()?
+    .into_ffmpeg_stderr()
+    .find(|line| line.contains("(audio)"))
+    .map(|line| line.split('\"').nth(1).map(|s| s.to_string()))
+    .context("No audio device found")?
+    .context("Failed to parse audio device")?;
+
+  println!("Listening to audio device: {}", audio_device);
+
+  // Second step: Capture audio and analyze w/ `ebur128` audio filter
+  // Loudness metadata will be printed to the FFmpeg logs
+  // Docs: <https://ffmpeg.org/ffmpeg-filters.html#ebur128-1>
+
+  let iter = FfmpegCommand::new()
+    .format("dshow")
+    .args("-audio_buffer_size 50".split(' ')) // reduces latency to 50ms (dshow-specific)
+    .input(format!("audio={audio_device}"))
+    .args("-af ebur128=metadata=1,ametadata=print".split(' '))
+    .format("null")
+    .output("-")
+    .spawn()?
+    .iter()?;
+
+  // Note: even though the audio device name may have spaces, it should *not* be
+  // in quotes (""). Quotes are only needed on the command line to separate
+  // different arguments. Since Rust invokes the command directly without a
+  // shell interpreter, args are already divided up correctly. Any quotes
+  // would be included in the device name instead and the command would fail.
+  // <https://github.com/fluent-ffmpeg/node-fluent-ffmpeg/issues/648#issuecomment-866242144>
+
+  let mut first_volume_event = true;
+  for event in iter {
+    match event {
+      FfmpegEvent::Error(e) | FfmpegEvent::Log(LogLevel::Error | LogLevel::Fatal, e) => {
+        eprintln!("{e}");
+      }
+      FfmpegEvent::Log(LogLevel::Info, msg) if msg.contains("lavfi.r128.M=") => {
+        if let Some(volume) = msg.split("lavfi.r128.M=").last() {
+          // Sample log output: [Parsed_ametadata_1 @ 0000024c27effdc0] [info] lavfi.r128.M=-120.691
+          // M = "momentary loudness"; a sliding time window of 400ms
+          // Volume scale is roughly -70 to 0 LUFS. Anything below -70 is silence.
+          // See <https://en.wikipedia.org/wiki/EBU_R_128#Metering>
+          let volume_f32 = volume.parse::<f32>().context("Failed to parse volume")?;
+          let volume_normalized: usize = max(((volume_f32 / 5.0).round() as i32) + 14, 0) as usize;
+          let volume_percent = ((volume_normalized as f32 / 14.0) * 100.0).round();
+
+          // Clear previous line of output
+          if !first_volume_event {
+            print!("\x1b[1A\x1b[2K");
+          } else {
+            first_volume_event = false;
+          }
+
+          // Blinking red dot to indicate recording
+          let time = std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .unwrap()
+            .as_secs();
+          let recording_indicator = if time % 2 == 0 { "🔴" } else { "  " };
+
+          println!(
+            "{} {} {}%",
+            recording_indicator,
+            repeat('█').take(volume_normalized).collect::<String>(),
+            volume_percent
+          );
+        }
+      }
+      _ => {}
+    }
+  }
+
+  Ok(())
+}

examples/terminal.rs renamed to examples/terminal_video.rs

@@ -188,27 +188,32 @@ pub fn spawn_stdout_thread(
 ) -> JoinHandle<()> {
   std::thread::spawn(move || {
     // Filter streams which are sent to stdout
-    let stdout_output_video_streams = output_streams
-      .iter()
-      .filter(|stream| stream.is_video())
-      .filter(|stream| {
-        outputs
-          .get(stream.parent_index as usize)
-          .map(|o| o.is_stdout())
-          .unwrap_or(false)
-      });
+    let stdout_streams = output_streams.iter().filter(|stream| {
+      outputs
+        .get(stream.parent_index as usize)
+        .map(|o| o.is_stdout())
+        .unwrap_or(false)
+    });
 
     // Exit early if nothing is being sent to stdout
-    if stdout_output_video_streams.clone().count() == 0 {
+    if stdout_streams.clone().count() == 0 {
+      tx.send(FfmpegEvent::Error("No streams found".to_owned()))
+        .ok();
       return;
     }
 
     // If the size of a frame can't be determined, it will be read in arbitrary chunks.
     let mut chunked_mode = false;
 
+    // Immediately default to chunked mode for non-video streams
+    let stdout_video_streams = stdout_streams.clone().filter(|stream| stream.is_video());
+    if stdout_video_streams.clone().count() == 0 {
+      chunked_mode = true;
+    }
+
     // Calculate frame buffer sizes up front.
     // Any sizes that cannot be calculated will trigger chunked mode.
-    let frame_buffer_sizes: Vec<usize> = stdout_output_video_streams
+    let frame_buffer_sizes: Vec<usize> = stdout_video_streams
       .clone()
       .map(|video_stream| {
         // Any non-rawvideo streams instantly enable chunked mode, since it's
@@ -240,7 +245,7 @@ pub fn spawn_stdout_thread(
     // but we can only keep track of them if the framerates match. It's
     // theoretically still possible to determine the expected frame order,
     // but it's not currently supported.
-    let output_framerates: Vec<f32> = stdout_output_video_streams
+    let output_framerates: Vec<f32> = stdout_video_streams
       .clone()
       .filter(|s| s.format == "rawvideo")
       .map(|video_stream| {

src/iter.rs

@@ -2,7 +2,10 @@
 
 use std::io::{BufRead, ErrorKind, Result};
 
-/// `BufRead::read_until` with multiple delimiters.
+/// Reads from the provided buffer until any of the delimiter bytes match.
+/// The output buffer will include the ending delimiter.
+/// Also skips over zero-length reads.
+/// See [`BufRead::read_until`](https://doc.rust-lang.org/std/io/trait.BufRead.html#method.read_until).
 pub fn read_until_any<R: BufRead + ?Sized>(
   r: &mut R,
   delims: &[u8],
@@ -17,10 +20,21 @@ pub fn read_until_any<R: BufRead + ?Sized>(
         Err(e) => return Err(e),
       };
 
+      let start_delims = if read == 0 {
+        available
+          .iter()
+          .take_while(|&&b| delims.iter().any(|&d| d == b))
+          .count()
+      } else {
+        0
+      };
+
       // NB: `memchr` crate would be faster, but it's unstable and not worth the dependency.
       let first_delim_index = available
         .iter()
-        .position(|b| delims.iter().any(|d| *d == *b));
+        .skip(start_delims)
+        .position(|&b| delims.iter().any(|&d| d == b))
+        .map(|i| i + start_delims);
 
       match first_delim_index {
         Some(i) => {
@@ -35,7 +49,17 @@ pub fn read_until_any<R: BufRead + ?Sized>(
     };
     r.consume(used);
     read += used;
-    if done || used == 0 {
+
+    if done {
+      return Ok(read);
+    }
+
+    // Discard final trailing delimiters
+    if used == 0 && buf.iter().all(|&b| delims.iter().any(|&d| d == b)) {
+      return Ok(0);
+    }
+
+    if used == 0 {
       return Ok(read);
     }
   }

src/read_until_any.rs

@@ -227,7 +227,7 @@ fn test_chunks() {
 }
 
 #[test]
-fn test_chunks_with_audio() {
+fn test_chunks_with_video_and_audio() {
   let mut chunks = 0;
   let mut frames = 0;
 
@@ -248,6 +248,26 @@ fn test_chunks_with_audio() {
     });
 
   assert!(chunks > 0);
+  assert!(frames == 0);
+}
+
+#[test]
+fn test_chunks_with_audio_only() -> anyhow::Result<()> {
+  let chunks = FfmpegCommand::new()
+    .args("-f lavfi -i sine=frequency=1000:duration=10".split(' '))
+    .format("s16le")
+    .args(&["-ac", "1"]) // Mono audio
+    .codec_audio("pcm_s16le")
+    .args(&["-ar", "44100"]) // Sample rate 44.1kHz
+    .pipe_stdout()
+    .spawn()?
+    .iter()?
+    .filter(|e| matches!(e, FfmpegEvent::OutputChunk(_)))
+    .count();
+
+  assert!(chunks > 0);
+
+  Ok(())
 }
 
 #[test]
@@ -676,3 +696,22 @@ fn test_stdout_interleaved_frames_fallback() -> anyhow::Result<()> {
 
   Ok(())
 }
+
+/// Make sure consecutive new lines in logs don't result in empty events.
+#[test]
+fn test_no_empty_events() -> anyhow::Result<()> {
+  let empty_events = FfmpegCommand::new()
+    .testsrc()
+    .rawvideo()
+    .spawn()?
+    .iter()?
+    .filter(|event| match event {
+      FfmpegEvent::Log(_, msg) if msg.is_empty() => true,
+      _ => false,
+    })
+    .count();
+
+  assert!(empty_events == 0);
+
+  Ok(())
+}