Integrated Audio Monitoring System

Overview

The Scream ecosystem provides a way to transport uncompressed audio over local networks via UDP (Multicast or Unicast). It acts as a virtual audio cable over Ethernet/Wi-Fi, replacing physical cables for VM-to-Host audio, smart factory alerts, and remote device monitoring.

🗺️ Architecture & Quick Start

Every sender pushes 1157-byte UDP packets to the multicast group 239.255.77.77:4010. Every receiver joined to that group plays the audio. There is no server and no handshake.

 ┌──────────────┐   ┌──────────────────┐   ┌──────────────┐
 │ Windows PC   │   │ Linux PC         │   │ Linux script │
 │ Scream driver│   │ pipewire-scream  │   │ screamplay   │
 └──────┬───────┘   └────────┬─────────┘   └──────┬───────┘
        │   UDP multicast 239.255.77.77:4010      │
        └──────────────┬─────┴────────────────────┘
                       ▼
       ┌───────────────┼────────────────┐
       ▼               ▼                ▼
  ScreamDroid     Unix receiver     ScreamReader
   (Android)        (Linux)          (Windows)

Quick Start

1. Pick a sender: Windows driver (don't skip the registry step), PipeWire sink on Linux, or screamplay for scripted alerts.
2. Pick a receiver: ScreamDroid on Android, or one of the desktop/embedded receivers.
3. Verify: if you hear nothing, check that packets reach the receiver before changing anything else.

🪟 Component 1 — Windows Sender (duncanthrax/scream)

Provides a virtual Windows sound card driver that routes all system audio over UDP.

Driver Installation

Installation itself does not require registry manipulation; you can simply use Windows Test Mode as shown below.

1. Ensure Secure Boot is disabled in your BIOS.
2. Open an Administrator command prompt and enable Test Mode:

   bcdedit /set testsigning on

   Reboot and confirm "Test Mode" appears on the desktop wallpaper.
3. Navigate to the driver folder and install:

   cd <scream folder>\Install\driver\x64
   pnputil /add-driver .\Scream.inf /install

4. Disable Test Mode and restart:

   bcdedit /set testsigning off

5. Open Sound Settings and set Scream as the default playback device.

Required Registry Configuration

You must configure the driver's settings in the registry under Computer\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Scream\Options (you will likely need to create the Options key). A reboot is required after changing these values.

🐧 Component 2 — Linux PipeWire Sender (zirize/pipewire-scream)

Creates a virtual audio sink in PipeWire. Audio routed to this sink is transmitted via the Scream protocol.

Build & Install

1. Install dependencies: pipewire-devel (or libpipewire-0.3-dev), cmake, gcc.
2. Clone and build:

   git clone https://github.com/zirize/pipewire-scream.git
   cd pipewire-scream
   cmake -B build && cmake --build build
   sudo cmake --install build

3. Configure auto-load:

   mkdir -p ~/.config/pipewire/pipewire.conf.d
   cp scream-sender.conf.example ~/.config/pipewire/pipewire.conf.d/scream-sender.conf
   systemctl --user restart pipewire

4. Confirm the sink exists, then make it the default output (or route individual apps to it with pavucontrol / qpwgraph):

   wpctl status            # the Scream sink should be listed under "Sinks"
   wpctl set-default <ID>  # ID taken from the list above

⌨️ Component 3 — CLI Audio Playback (zirize/screamplay)

Streams audio files directly onto the Scream network without needing a virtual sound card. Ideal for automation and alerting scripts.

1. Install dependencies: libsndfile1-dev, libsamplerate0-dev.
2. Clone and build:

   git clone https://github.com/zirize/screamplay.git
   cd screamplay && make

3. Play an audio file:

   ./screamplay alert.wav

   Automatically resamples to 48 kHz. Supports WAV, FLAC, OGG, AIFF, and MP3.
4. Hook it into monitoring. For example, play an alarm when a host stops answering ping:

   ping -c 3 -W 2 192.168.0.50 >/dev/null || ./screamplay alarm.wav

📱 Component 4 — Android Receiver (zirize/screamdroid)

A dedicated Android receiver that plays PC audio through your phone over Wi-Fi. It is highly optimized for battery efficiency and daily usage.

Key Features

• Automatic Call Muting: Detects active incoming/outgoing calls (via Audio Focus, without requiring invasive Phone state permissions) and gracefully mutes the network stream.
• Foreground Service: Reliable background playback even when the screen is locked or the app is dismissed.
• Dynamic Buffer Tuning: Lowers latency on fast networks and scales up buffering gracefully if the connection jitters.
• Installation: Download the APK directly from GitHub Releases.

📡 Component 5 — Other Receivers Setup

You can mix and match receivers. Multiple receivers can listen to the same multicast group (239.255.77.77:4010).

cd scream/Receivers/unix
cmake -B build && cmake --build build
./build/scream -i eth0       # multicast
./build/scream -u -p 4011    # unicast

🎛️ Advanced Setup: Central Audio Relay & Mixing

By default, the Scream multicast protocol does not properly support multiple simultaneous audio sources on the same network (streams will collide and cause severe audio glitches). If you need to monitor multiple PCs or VMs simultaneously, you can use a Linux host as a central mixing relay.

For a complete, step-by-step tutorial on configuring the Linux Relay (including routing with qpwgraph and setting up Unicast configurations), check out the Detailed Relay Setup Guide in the pipewire-scream documentation.

How It Works

1. Senders (Peers/VMs): Each Windows PC or VM is configured to send its audio via Unicast to a specific, unique port on the Linux Relay (e.g., PC 1 to port 4011, PC 2 to 4012).
2. Linux Relay (Mixer): The Linux host runs multiple instances of the Scream Unix Receiver (one for each port). These receivers output audio into a single, shared PulseAudio or PipeWire virtual sink, effectively mixing the sounds.
3. Broadcaster: The Linux host uses pipewire-scream to capture this mixed sink and broadcasts the final, unified stream via Multicast (port 4010) to all your receivers.

🔍 Verifying the Stream & Firewall

Most "no audio" problems are network problems. First check whether packets reach the receiver host:

sudo tcpdump -n -i any udp port 4010
# expected: a steady stream of lines ending in "UDP, length 1157"

If nothing shows up, open the port on the receiver (and on the relay, if you use one):

sudo ufw allow 4010/udp
# or (firewalld)
sudo firewall-cmd --permanent --add-port=4010/udp
sudo firewall-cmd --reload

netsh advfirewall firewall add rule ^
  name="Scream" dir=in action=allow ^
  protocol=UDP localport=4010

If packets appear on a wired host but not over Wi‑Fi, the access point is probably filtering or rate-limiting multicast. Switch that sender to unicast.

🩺 Troubleshooting

📡 Protocol Reference

The Scream wire format is simple, which makes it easy to write your own sender or receiver (e.g. on a microcontroller).

Bandwidth: 48 kHz × 16-bit × 2 ch ≈ 1.5 Mbps. 5.1 channels at 48 kHz/16-bit ≈ 4.6 Mbps.