ConnectFlow

A Python-GTK application for streaming audio to multiple Bluetooth devices simultaneously. ConnectFlow simplifies the process of broadcasting system audio to all your connected Bluetooth speakers and headphones through an intuitive interface.

Built to replace the need for manually configuring Helvum, Pavucontrol, and complex Pipewire commands, ConnectFlow handles virtual sink management and device routing automatically.

Screenshots

ConnectFlow application running with the main interface

Features

• 🎵 Multi-Device Audio Broadcasting: Stream audio to multiple Bluetooth devices simultaneously
• 🔧 Automated Virtual Sink Management: Handles Pipewire configuration automatically
• 📱 Bluetooth Device Management: Simple connection and profile management for audio devices
• 🎛️ Individual Volume Control: Adjust volume per device or control all devices together
• 💾 Session Management: Save and restore device configurations
• 🖥️ Clean GTK Interface: Intuitive user interface built with GTK 4

Important Notes

⚠️ Dependencies: Some Python packages or system dependencies may cause compatibility issues depending on your configuration. Ensure all prerequisites are properly installed before running the application.

⚠️ Audio Limitations: Due to Bluetooth and hardware constraints, the application broadcasts stereo audio to one device and mono audio to additional devices. This is a limitation of the underlying audio stack.

Installation

Prerequisites

Before installation, ensure you have:

• Python 3.8 or higher
• GTK 4
• Pipewire audio server
• BlueZ Bluetooth stack
• PyGObject

Install Dependencies

Install the required Python packages:

pip install -r requirements.txt

System Requirements

Verify these system components are installed and running:

• Pipewire audio server
• BlueZ Bluetooth stack
• GTK 4 development libraries

Usage

1. Launch the application:

   python main.py

2. Device Discovery:

   • The application automatically scans for available Bluetooth devices
   • Paired devices will appear in the device list

3. Select Devices:

   • Choose which Bluetooth devices to include in your broadcast group
   • ConnectFlow creates a virtual sink for multi-device output

4. Start Broadcasting:

   • System audio is automatically routed to all selected devices
   • Audio streams simultaneously to all connected devices

5. Volume Management:

   • Adjust individual device volumes as needed
   • Save your configuration for future sessions

How It Works

ConnectFlow operates through the following workflow:

1. Initialization: Connects to Pipewire and loads saved configurations
2. Device Discovery: Scans for available Bluetooth audio devices
3. Virtual Sink Creation: Creates a Pipewire virtual sink for multi-device output
4. Device Connection: Establishes connections to selected Bluetooth devices
5. Audio Routing: Routes system audio through the virtual sink to all devices
6. Volume Control: Provides individual and master volume management
7. Session Persistence: Saves configurations for future use

Technical Implementation

ConnectFlow uses Pipewire's libpipewire-module-combine-stream to create a virtual sink:

context.modules = [
  { name = libpipewire-module-combine-stream
    args = {
      combine.mode = sink
      node.name = "connectflow_sink"
      node.description = "Connectflow Output"
      combine.latency-compensate = false
      combine.props = { audio.position = [ FL FR FC LFE SL SR ] }
      stream.rules = [
        { matches = [ { media.class = "Audio/Sink" } ]
          actions = { create-stream = {
            combine.audio.position = [ FL FR FC LFE SL SR ]
            audio.position = [ FL FR FC LFE SL SR ]
          } }
        }
      ]
    }
  }
]

Development

Project Structure

connectflow/
├── main.py                 # Application entry point
├── requirements.txt        # Python dependencies
├── config/                 # Configuration templates
├── core/                   # Core functionality
│   ├── audio/             # Audio and sink management
│   └── bluetooth/         # Bluetooth device handling
├── ui/                    # User interface components
│   ├── components/        # GTK widgets and dialogs
│   ├── windows/          # Main application windows
│   └── styles/           # CSS styling
└── utils/                 # Common utilities and helpers

Contributing

Contributions are welcome! To contribute:

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Commit your changes: git commit -m 'Add feature description'
4. Push to the branch: git push origin feature-name
5. Submit a pull request

Development Setup

To set up a development environment:

1. Clone the repository:

   git clone https://github.com/ash-baseplate/ConnectFlow.git
   cd ConnectFlow

2. Create a virtual environment:

   python -m venv venv
   source venv/bin/activate  # Windows: venv\Scripts\activate

3. Install dependencies:

   pip install -r requirements.txt

4. Run the application:

   python main.py

Acknowledgments

This project builds upon excellent open-source technologies:

• Pipewire - Modern audio server for Linux
• BlueZ - Official Linux Bluetooth protocol stack
• GTK - Cross-platform widget toolkit
• PyGObject - Python bindings for GTK

Support

For issues, questions, or feature requests, please open an issue on GitHub.

---

Note: This project is currently in active development. Some features may not be fully implemented yet.