# SongRec: Shazam recognition on Linux

> SongRec is a Rust implementation of a Shazam client for Linux, with file recognition, microphone input, continuous detection, a GUI, and CSV history export. It suits Linux users who want Shazam recognition without relying on the official client, although Flatpak sandboxing limits some command-line workflows.

**marin-m/SongRec** — An open-source Shazam client for Linux, written in Rust.

- Repository: https://github.com/marin-m/SongRec
- Website: https://songrec.fossplant.re/
- Stars: 2,003 · Forks: 145
- Language: Rust
- License: GPL-3.0
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/marin-m-songrec

## SongRec's Linux recognition workflow

SongRec addresses a specific gap for Linux users: recognizing a track through the Shazam service from a Linux desktop. It can inspect an arbitrary audio file, listen through the microphone, or recognize sound arriving from the speakers. The application offers both a graphical interface and a command-line interface. Its GUI also keeps a history of recognized songs and can export that history to CSV, while its continuous microphone mode can use a selected input device.

The intended users are people who already have Linux audio workflows and want recognition integrated into that environment. SongRec is not a local music catalog matcher. According to its documentation, the client generates a fingerprint and sends frequency-peak data to Shazam servers, which perform the database lookup. Recognition therefore depends on network access and on a service that SongRec does not operate.

That distinction matters when choosing the tool. A user searching for an entirely offline identifier for privately held audio will not find that behavior documented here. SongRec is better understood as a Linux front end for Shazam recognition. It can identify familiar commercial recordings, but the README does not promise recognition of unreleased material, isolated sound effects, speech, or custom audio that is absent from the service's reference database.

## Spectrogram fingerprints and server-side matching

SongRec's documented mechanism follows the publicly described Shazam fingerprinting approach. Audio is downsampled to 16 KHz and represented as a spectrogram, a time and frequency graph whose amplitude values describe the sound. The client identifies frequency peaks, which correspond to stable harmonic features in voices and instruments.

The signal is divided into four documented frequency bands: 250-520 Hz, 520-1450 Hz, 1450-3500 Hz, and 3500-5500 Hz. This partition allows another band to contribute useful matching information when one band is excessively affected by noise. SongRec sends the selected peaks to Shazam, where the service searches its reference fingerprints for neighboring peaks that also occur together in the submitted fingerprint.

This design keeps much of the matching workload on the server. The Rust client handles local signal processing and interaction with the recognition service rather than shipping a complete song database. The repository manifest supports that implementation with `rustfft` and `realfft` for frequency analysis, `rodio` for audio decoding, resampling, and playback-related tasks, and libraries such as `serde_json`, `uuid`, `byteorder`, and `crc32fast` for protocol and structured data work. The README describes the algorithm at a conceptual level, but it does not publish a complete protocol specification or guarantee identical treatment for every file format.

## Installing SongRec through Linux packages

For Ubuntu, the README recommends the project PPA. The following commands add its signing key, register the repository, install SongRec, and launch it. A successful installation should make the `songrec` command available and open the application's interface.

```bash
wget -qO- 'http://keyserver.ubuntu.com/pks/lookup?op=get&search=0x6888550b2fc77d09' | sudo tee /etc/apt/trusted.gpg.d/songrec.asc
sudo apt-add-repository ppa:marin-m/songrec -y -u
sudo apt install songrec -y
songrec
```

Arch Linux has a shorter package path. After installation, running `songrec` performs the same first launch shown in the Ubuntu instructions.

```bash
sudo pacman -S songrec
songrec
```

Flatpak is documented for all distributions, including systems without native packages. Here, `flathub` is added only if it is absent, the SongRec application is installed for the current user, and the Flatpak application identifier is launched.

```bash
sudo apt install flatpak -y
flatpak remote-add --user flathub https://flathub.org/repo/flathub.flatpakrepo --if-not-exists
flatpak install --user flathub re.fossplant.songrec -y
flatpak run re.fossplant.songrec
```

The Flatpak GUI is expected to work, but the README warns that filesystem sandboxing can prevent some command-line features from accessing files. Native packages are therefore the better starting point when command-line file recognition depends on paths outside the sandbox.

## First recognition and media-format requirements

The simplest documented first use is to launch SongRec after installation. The application can then recognize a track from an audio file, capture audio from a microphone, or listen to speakers. Continuous detection is available through microphone input, and the GUI records recognized songs in a history that can be exported to CSV. The README does not provide a complete GUI click-by-click walkthrough or a table of command-line flags for these operations, so it would be inaccurate to invent menu names or arguments.

SongRec has built-in support for common audio containers and codecs through the `rodio` configuration in `Cargo.toml`. The README explicitly identifies WAV, OGG, FLAC, and MP3 as formats for which no additional conversion package is required. If the source file uses another supported or convertible format, install `ffmpeg`. This is a practical precondition for batch use or for files arriving from sources that use formats outside that list.

For source builds, the repository requires Rust 1.88 or later and `libadwaita` 1.8 or newer for the GUI. The README also warns that compilation must use release mode for correct performance. It links to the standard Rust installation tool and gives distribution-specific dependency commands. The crate manifest identifies the current package version as 0.7.6 and uses Rust edition 2024. A source build therefore adds dependency installation and native GUI development libraries to the cost of using a packaged installation.

## Flatpak sandboxing and service-dependent limits

The clearest limitation is the conflict between Flatpak convenience and filesystem access. SongRec's Flatpak installation should provide a working GUI, but the README says some CLI features may be unusable because of sandboxing. Users who rely on recognizing files from arbitrary directories should read this as a package-selection issue, not a recognition algorithm issue. Native Arch or Ubuntu packages avoid the stated Flatpak filesystem boundary, although they still require appropriate local permissions.

Recognition also depends on remote processing. The frequency peaks are sent to Shazam servers, and the server performs the reference lookup. SongRec does not claim that recognition works without a network connection, nor does it document behavior when Shazam changes its service, rate-limits requests, blocks a client, or becomes unavailable. The repository can provide the client implementation, but it cannot guarantee the continued availability or policy behavior of that external service.

SongRec is also the wrong tool when privacy rules prohibit sending derived audio fingerprints to a third party. The documented flow sends peak information rather than the complete audio file, but the README does not provide a local-only recognition mode or a formal data-handling guarantee. Users handling confidential recordings should verify the service terms and network policy before using the application. Finally, macOS is not officially supported. The README mentions XQuartz, the `GSK_RENDERER=caio` environment variable, and possible additional work, but describes those as troubleshooting steps rather than a supported platform path.

## Native Rust client versus the Python implementation

SongRec includes a separate Python version that the author created before rewriting the client in Rust. This is a real alternative within the repository, but its scope is narrower. The Python version is documented as command-line only and supports file recognition only. It does not offer the Rust version's GUI, microphone recognition, continuous detection, speaker input, or CSV history interface.

The Rust rewrite was motivated by performance, and the current Cargo manifest reflects a larger application with FFT processing, GTK and libadwaita dependencies, audio backends, command-line parsing, CSV support, and database integration through DBus-related dependencies. The Python implementation may be easier to inspect for the basic file-recognition path, but selecting it means giving up the main interface features that motivate many users to choose SongRec. The README presents it primarily for demonstration, so the native Rust application is the more relevant adoption target for everyday recognition on Linux.

Maintenance is current enough to evaluate, with the last push recorded on 2026-10-15 and release 0.7.6 carrying the description "Memory allocation fix." That is recent activity, but upgrades can still involve native audio and GUI libraries. SongRec is licensed GPL-3.0+ in `Cargo.toml`. Distribution through operating-system repositories or Flatpak can affect packaging and upgrade ownership, while source-based users must account for Rust 1.88, libadwaita 1.8, and the other build dependencies themselves.

## Conclusion

SongRec is a practical choice for Linux users who need file recognition, microphone capture, continuous detection, or a GUI recognition history without the official Shazam application. It is less suitable for users who need offline recognition, a fully isolated Flatpak workflow, or official macOS support. Before adoption, verify that the recognition service is acceptable for your use, install `ffmpeg` if you need formats beyond WAV, OGG, FLAC, and MP3, and confirm that your chosen package method exposes the required files to the command-line interface. For the documented Linux distribution package, SongRec 0.7.6 is the concrete release to evaluate first.

## FAQ

### How do I install SongRec on Ubuntu?

The README recommends adding the `ppa:marin-m/songrec` repository and then installing the `songrec` package. It also documents Arch Linux packages and a Flatpak installation for other distributions.

### Can SongRec recognize audio from a microphone?

Yes. SongRec documents microphone recognition, continuous song detection, and selection of an input device. It can also recognize audio coming from speakers rather than only from a microphone.

### Does SongRec work without the internet?

The documented Shazam workflow sends frequency peaks to servers for database lookup, so the README does not present SongRec as an offline recognition tool. No local-only recognition mode is documented.

## Sources

- [License: GPL-3.0](https://github.com/marin-m/SongRec/blob/main/LICENSE)
- [marin-m/SongRec on GitHub](https://github.com/marin-m/SongRec)
- [Project website](https://songrec.fossplant.re/)
- [README](https://github.com/marin-m/SongRec/blob/main/README.md)
- [Releases](https://github.com/marin-m/SongRec/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/marin-m-songrec