Stream Catcher

A simple audio recorder for Linux that automatically captures and saves songs playing from MPRIS-enabled media players (like Spotify, Celluloid, etc.). It comes with a Cinnamon desktop applet for easy control.

Features

• Automatic Recording: Detects when a new song starts and begins recording automatically.
• Metadata & Album Art: Saves the recorded audio in an .mp4 container with the correct title, artist, album, and embedded album art.
• Playback Detection: Intelligently saves the file only if the song has played to near completion, avoiding partial recordings from skips.
• Cinnamon Applet: Provides a simple user interface in your desktop panel to start/stop the service and view the currently recording track.

Requirements

• A Linux distribution with the Cinnamon Desktop Environment.
• build-essential, git, and pkg-config.
• FFmpeg development libraries.
• D-Bus development libraries.

Installation

1. Clone the Repository

Open a terminal and run:

git clone [https://github.com/EvanParden/stream-catcher.git](https://github.com/EvanParden/stream-catcher.git)
cd stream-catcher

2. Install Dependencies

On Debian-based systems (like Ubuntu, Linux Mint):

sudo apt-get update
sudo apt-get install build-essential pkg-config libavformat-dev libavcodec-dev libavdevice-dev libswresample-dev libavutil-dev libdbus-1-dev

3. Compile the Recorder

Compile the C++ backend program:

g++ src/main.cpp -o recorder $(pkg-config --cflags --libs libavformat libavcodec libavdevice libswresample libavutil dbus-1) -lpthread

4. Install the Program and Applet

Run the included installation script (or perform the steps manually):

chmod +x install.sh
./install.sh

(You may need to create a simple install.sh script that moves the compiled recorder to ~/.local/bin/ and copies the applet directory to ~/.local/share/cinnamon/applets/)

5. Reload Cinnamon

To make the applet available, restart the Cinnamon shell by pressing Alt+F2, typing r, and pressing Enter.

Usage

1. Right-click on your Cinnamon panel, select "Applets," find "Stream Catcher" in the list, and click the + button to add it.
2. Click the new record icon on your panel to open the menu.
3. Use the toggle switch to enable the recording service.
4. Play music in a supported player. The applet will display the current song, and it will be saved to ~/Music/Recordings when finished.

License

This project is licensed under the MIT License. See the LICENSE file for details.