Skip to content

README.md

Latest commit

 

History

History
97 lines (68 loc) · 4.53 KB

README.md

File metadata and controls

97 lines (68 loc) · 4.53 KB
Raw

Linux Virtual Audio Cable (vcable)

A minimalist tool to create a "Virtual Speaker" and "Virtual Mic" in Linux (supports PipeWire & PulseAudio). Highly useful for routing clean audio with filters (Noise Suppression/EQ) from OBS Studio to communication apps like Discord, Zoom, or Google Meet without bleeding into Desktop Audio.

Installation

⚠️ CRITICAL: Before running the installer, please close all applications actively using your microphone or speakers (e.g., OBS Studio, Discord, Zoom, or web browsers). The installer will restart your core audio engine, which may cause active applications to freeze or drop audio if left open.

Ensure you have the pulseaudio-utils (pactl) dependency installed. Run the installer script:

chmod +x vcable-installer.sh
./vcable-installer.sh

This script is 100% safe, requires zero root/sudo privileges, and deploys the logic entirely in user-space directories (~/.local/bin/).

Setup Guide (General Concept)

The architecture of this tool is simple: Audio sent to the Virtual Speaker will automatically flow out through the Virtual Mic. Here is how to configure your applications based on their role:

1. The Sender App (e.g., OBS Studio, Streamlabs) This is the app where you process your microphone (adding EQ, Noise Suppression, etc.). You need to "monitor" or output that processed audio into the virtual bridge.

  • In OBS Studio:
    • Go to Settings > Audio > Advanced.
    • Change the Monitoring Device to Virtual Speaker.
    • In your main Audio Mixer panel, click the gear icon on your hardware Mic.
    • Select Advanced Audio Properties.
    • Set your hardware Mic to Monitor Only (mute output).

2. The Receiver App (e.g., Discord, Zoom, Google Meet) This is the communication app where you want your friends/colleagues to hear your processed voice.

  • In Discord / Zoom:
    • Go to Audio/Voice Settings.
    • Set your Input Device (Microphone) to Virtual Mic.
    • CRITICAL: Disable all built-in audio effects in the receiver app (e.g., Krisp Noise Suppression, Echo Cancellation, Automatic Gain Control). Since OBS is already filtering your voice, stacking double filters will heavily distort your audio.

Diagnostics & Status Check (Troubleshooting)

If the audio flow encounters issues, run these native Linux diagnostic commands in your terminal:

Check if the background service is running:

systemctl --user status vcable.service

Check if the virtual cables are registered in the system:

pactl list short sinks | grep Virtual
pactl list short sources | grep Virtual

Check the physical PipeWire routing (PipeWire only):

pw-link -l | grep Virtual

(It should show VirtualSpeaker:monitor directly connected to VirtualMic:input).

How to Uninstall (System Cleanup)

Because the architecture is entirely transparent, you can completely remove this tool and clean your system by executing these native OS commands:

# 1. Stop and disable the startup service
systemctl --user disable --now vcable.service

# 2. Remove the Systemd configuration file
rm -f ~/.config/systemd/user/vcable.service

# 3. Remove the core routing script
rm -f ~/.local/bin/vcable-bridge.sh

# 4. Flush the memory manager cache
systemctl --user daemon-reload

# 5. Restart the audio daemon to instantly clear virtual cables from active memory
systemctl --user restart pipewire pipewire-pulse wireplumber || true

Your Linux audio system is now 100% restored to its default state.

Acknowledgements & Credits

Inspiration: This project was heavily inspired by the foundational work done by steven3363. While their repository utilizes a native PipeWire module-loopback .conf architecture, vcable diverges by employing a cross-compatible (PipeWire & PulseAudio) minimalist Bash architecture, utilizing direct pw-link port bridging and interactive dependency resolution for a more streamlined, crash-resistant installation. Respect and credit to the original author for the core concept of Linux virtual audio routing.

AI Collaboration: The architectural logic, debugging strategy, and core vision of this tool were conceptualized by the repository owner, while the script generation, code refactoring, and English documentation were co-authored with the assistance of Google's Gemini AI. A true human-AI engineering collaboration.

License

This project is licensed under the GNU General Public License v3.0 (GPL-3.0) - see the LICENSE file for details.