lowfi

https://github.com/talwat/lowfi
Admin
lowfi is a minimal terminal-based lofi music player written in Rust that streams ambient music with...
Tokens:7,287
Snippets:80
Trust Score:9.5
License:MIT
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install lowfi on openSUSE

Source: https://github.com/talwat/lowfi/blob/main/README.md

Install lowfi using the `zypper` package manager on openSUSE.

```sh
zypper install lowfi
```

--------------------------------

### Interact with lowfi during playback

Source: https://context7.com/talwat/lowfi/llms.txt

Example session demonstrating keyboard controls for playback and bookmarking.

```sh
# Example session
lowfi
# Press 'p' or Space to pause/resume
# Press 's' to skip to next track
# Press '+' or 'k' to increase volume
# Press 'b' to bookmark current track
# Press 'q' to quit
```

--------------------------------

### Install lowfi via Cargo

Source: https://context7.com/talwat/lowfi/llms.txt

Use these commands to install the binary or build from source with specific features.

```sh
# Standard installation
cargo install lowfi

# With MPRIS support (Linux only)
cargo install lowfi --features mpris

# With extra audio format support (FLAC, Vorbis, WAV)
cargo install lowfi --features extra-audio-formats

# Build from source with all features
git clone https://github.com/talwat/lowfi
cd lowfi
cargo build --release --all-features
./target/release/lowfi
```

--------------------------------

### Install lowfi from AUR

Source: https://github.com/talwat/lowfi/blob/main/README.md

Install lowfi using the AUR helper `yay` on Arch Linux.

```sh
yay -S lowfi
```

--------------------------------

### Add Debian/Ubuntu Repository and Install lowfi

Source: https://github.com/talwat/lowfi/blob/main/README.md

Add an unofficial Debian repository for lowfi and install it using apt. This involves importing a GPG key and adding a source list entry.

```sh
curl -sS https://debian.griffo.io/3B9335DF576D3D58059C6AA50B56A1A69762E9FF.asc | gpg --dearmor --yes -o /etc/apt/trusted.gpg.d/debian.griffo.io.gpg
echo "deb https://debian.griffo.io/apt $(lsb_release -sc 2>/dev/null) main" | sudo tee /etc/apt/sources.list.d/debian.griffo.io.list
sudo apt install -y lowfi
```

--------------------------------

### Install lowfi with Cargo

Source: https://github.com/talwat/lowfi/blob/main/README.md

Install the lowfi application using Cargo, the Rust package manager. Ensure your Cargo bin directory is in your PATH.

```sh
cargo install lowfi
```

```sh
cargo install lowfi --features mpris
```

--------------------------------

### Basic Download List Format

Source: https://github.com/talwat/lowfi/blob/main/README.md

This format is used for specifying URLs to download. The first line acts as a base URL, prepended to subsequent track URLs. Ensure a trailing '/' in the header if tracks do not start with a protocol.

```txt
https://lofigirl.com/wp-content/uploads/
2023/06/Foudroie-Finding-The-Edge-V2.mp3
2023/04/2-In-Front-Of-Me.mp3
https://file-examples.com/storage/fe85f7a43b689349d9c8f18/2017/11/file_example_MP3_1MG.mp3
```

--------------------------------

### Enable Fedora COPR and Install lowfi

Source: https://github.com/talwat/lowfi/blob/main/README.md

Enable an unofficial COPR repository for lowfi on Fedora and install it using dnf.

```sh
sudo dnf copr enable furqanhun/lowfi
sudo dnf install lowfi
```

--------------------------------

### Run lowfi with command-line options

Source: https://context7.com/talwat/lowfi/llms.txt

Launch the player with various UI and playback configurations.

```sh
# Start playing with default settings
lowfi

# Start paused
lowfi --paused

# Use minimalist mode (hide control bar)
lowfi --minimalist

# Borderless UI
lowfi --borderless

# Use alternate terminal screen
lowfi --alternate

# Combine multiple options
lowfi --alternate --minimalist --borderless
```

--------------------------------

### Manual Build and Run lowfi

Source: https://github.com/talwat/lowfi/blob/main/README.md

Manually clone the lowfi repository, build the release binary, and run it. This method is useful for debugging.

```sh
git clone https://github.com/talwat/lowfi
cd lowfi

# If you want an actual binary
cargo build --release --all-features
./target/release/lowfi

# If you just want to test
cargo run --all-features
```

--------------------------------

### Initialize and run the Player

Source: https://context7.com/talwat/lowfi/llms.txt

Manages the player lifecycle, including initialization with arguments and an audio mixer, running the main event loop, and performing cleanup.

```rust
use lowfi::player::{Player, Current};
use lowfi::Args;

// Player initialization and lifecycle
async fn example() -> lowfi::Result<()> {
    let args = Args::parse();
    let stream = lowfi::audio::stream()?;

    // Initialize player with args and audio mixer
    let (mut player, tasks) = Player::init(args, stream.mixer()).await?;

    // Run the main event loop
    tokio::select! {
        r = player.run() => r,
        r = tasks => r,
    }?;

    // Cleanup and persist state (volume, bookmarks)
    player.close().await?;
    Ok(())
}
```

--------------------------------

### Download List with Local File Paths

Source: https://github.com/talwat/lowfi/blob/main/README.md

Use the 'file://' protocol to specify local file paths for headers or tracks. This is useful for using local directories as base URLs or downloading local files.

```txt
file:///home/user/Music/
file.mp3
file:///home/user/Other Music/second-file.mp3
```

--------------------------------

### Configure lowfi behavior

Source: https://context7.com/talwat/lowfi/llms.txt

Adjust performance and UI settings using command-line flags.

```sh
# Set custom buffer size (minimum 2, default 5)
lowfi --buffer-size 10

# Set download timeout in seconds (default 16)
lowfi --timeout 30

# Set UI width from 0 to 32 (default 3)
lowfi --width 5

# Set UI refresh rate (default 12 FPS)
lowfi --fps 30

# Enable debug mode to see ALSA and other logs
lowfi --debug

# Show clock in UI
lowfi --clock
```

--------------------------------

### Load and manage track lists

Source: https://context7.com/talwat/lowfi/llms.txt

Demonstrates loading track lists from different sources and creating them programmatically.

```rust
use lowfi::tracks::List;

async fn example() -> lowfi::tracks::Result<()> {
    // Load the default embedded chillhop list
    let list = List::load("chillhop").await?;

    // Load from data directory (e.g., ~/.local/share/lowfi/mytracks.txt)
    let list = List::load("mytracks").await?;

    // Load from absolute path
    let list = List::load("/home/user/Music/custom.txt").await?;

    // Access list properties
    println!("List name: {}", list.name);
    println!("Base URL: {}", list.header());
    println!("Track count: {}", list.lines.len() - 1);

    // Get a random track path and optional custom name
    let mut rng = fastrand::Rng::new();
    let (path, display_name) = list.random_path(&mut rng);
    println!("Random track: {}", path);
    if let Some(name) = display_name {
        println!("Display name: {}", name);
    }

    Ok(())
}

// Create a list programmatically
fn create_list() -> List {
    let content = r#"https://example.com/music/
track1.mp3
track2.mp3!Custom Name
https://other.com/direct.mp3"#;

    List::new("my-list", content, None)
}
```

--------------------------------

### Load custom track lists

Source: https://context7.com/talwat/lowfi/llms.txt

Specify track sources using built-in lists, local files, or bookmarks.

```sh
# Use built-in chillhop list (default)
lowfi --track-list chillhop

# Load a list from data directory (~/.local/share/lowfi/ on Linux)
lowfi --track-list minipop

# Load from a specific file path
lowfi --track-list ~/Music/mytracks.txt

# Play bookmarked tracks
lowfi --track-list bookmarks
```

--------------------------------

### Process track data structures

Source: https://context7.com/talwat/lowfi/llms.txt

Demonstrates working with Queued and Decoded track data, including decoding and manual creation.

```rust
use lowfi::tracks::{Queued, Decoded, Info};
use bytes::Bytes;

// Queued: Downloaded but not decoded
fn process_queued(queued: Queued) -> lowfi::tracks::Result<()> {
    println!("Track: {}", queued.display);
    println!("Path: {}", queued.path);
    println!("Raw data: {} bytes", queued.data.len());

    // Decode the track for playback
    let decoded = queued.decode()?;
    play_decoded(decoded);
    Ok(())
}

// Decoded: Ready for playback with full metadata
fn play_decoded(decoded: Decoded) {
    let info = &decoded.info;
    println!("Playing: {}", info.display);
    println!("Path: {}", info.path);
    println!("Display width: {} chars", info.width);

    if let Some(duration) = info.duration {
        println!("Duration: {:?}", duration);
    }

    // Convert back to track list entry format
    let entry = info.to_entry();
    println!("Entry format: {}", entry);
    // Output: "path/to/track.mp3!Display Name"
}

// Create a queued track manually
fn create_queued(path: String, data: Bytes) -> lowfi::tracks::Result<Queued> {
    // Auto-format display name from path
    Queued::new(path.clone(), data.clone(), None)?;

    // Or specify custom display name
    Queued::new(path, data, Some("My Custom Track".to_string()))
}
```

--------------------------------

### Build and Run Scraper Feature

Source: https://context7.com/talwat/lowfi/llms.txt

Commands to build the project with the scrape feature and execute scraping tasks.

```bash
# Build with scrape feature
cargo build --features scrape

# Scrape from supported sources
lowfi scrape archive   # Scrape archive.org
lowfi scrape chillhop  # Scrape chillhop.com
lowfi scrape lofigirl  # Scrape lofigirl.com (deprecated)
```

--------------------------------

### Manage bookmarks

Source: https://context7.com/talwat/lowfi/llms.txt

Bookmarks are saved to a local file and can be played back as a track list.

```sh
# While playing, press 'b' to bookmark/unbookmark current track

# Play all bookmarked tracks
lowfi --track-list bookmarks

# Bookmarks are stored at:
# Linux: ~/.local/share/lowfi/bookmarks.txt
# macOS: ~/Library/Application Support/lowfi/bookmarks.txt
# Windows: %appdata%\Roaming\lowfi\bookmarks.txt
```

--------------------------------

### Identify Data Directory Paths

Source: https://context7.com/talwat/lowfi/llms.txt

Platform-specific file system paths for configuration and data storage.

```bash
# Data directory (track lists, bookmarks)
# Linux:   ~/.local/share/lowfi/
# macOS:   ~/Library/Application Support/lowfi/
# Windows: %appdata%\Roaming\lowfi\

# Config directory (volume settings)
# Linux:   ~/.config/lowfi/
# macOS:   ~/Library/Application Support/lowfi/
# Windows: %appdata%\Roaming\lowfi\

# Files stored:
# - bookmarks.txt    - Bookmarked tracks
# - volume.txt       - Persistent volume setting
# - *.txt            - Custom track lists
```

--------------------------------

### Manage Bookmarks with Rust

Source: https://context7.com/talwat/lowfi/llms.txt

Load, toggle, and save track bookmarks using the Bookmarks API.

```rust
use lowfi::bookmark::Bookmarks;
use lowfi::tracks::Info;

async fn manage_bookmarks() -> Result<(), lowfi::bookmark::Error> {
    // Load existing bookmarks from disk
    let mut bookmarks = Bookmarks::load().await?;

    // Check if a track is bookmarked
    // (requires a tracks::Info instance from a decoded track)
    // let is_bookmarked = bookmarks.bookmarked(&track_info);

    // Toggle bookmark status (returns new bookmarked state)
    // let now_bookmarked = bookmarks.bookmark(&track_info)?;

    // Save bookmarks to disk
    bookmarks.save().await?;

    // Bookmarks file location
    let path = Bookmarks::path().await?;
    println!("Bookmarks stored at: {}", path.display());

    Ok(())
}
```

--------------------------------

### Handle track download progress

Source: https://context7.com/talwat/lowfi/llms.txt

Processes track download states, including queued tracks ready for playback and ongoing download progress.

```rust
use lowfi::downloader::{Progress, Output, Handle};
use lowfi::tracks::List;

// The downloader runs as a background task and fills a queue
// Access it through the Handle returned by Tasks::downloader()

fn handle_track(handle: &mut Handle) {
    match handle.track() {
        Output::Queued(queued) => {
            // Track is ready to play
            println!("Track ready: {}", queued.display);
            println!("Path: {}", queued.path);
            println!("Data size: {} bytes", queued.data.len());

            // Decode and play
            let decoded = queued.decode().expect("decode failed");
            println!("Duration: {:?}", decoded.info.duration);
        }
        Output::Loading(Some(progress)) => {
            // Download in progress
            let percent = progress.get() * 100.0;
            println!("Downloading: {:.1}%", percent);
        }
        Output::Loading(None) => {
            println!("Waiting for download to start...");
        }
    }
}
```

--------------------------------

### Manage Persistent Volume with Rust

Source: https://context7.com/talwat/lowfi/llms.txt

Load and save volume settings, converting between integer percentages and float values for playback.

```rust
use lowfi::volume::PersistentVolume;

async fn manage_volume() -> Result<(), lowfi::volume::Error> {
    // Load saved volume (defaults to 100 if not set)
    let volume = PersistentVolume::load().await?;

    // Get volume as integer percentage (0-100)
    println!("Volume: {}%", volume.inner);

    // Get volume as float for playback (0.0-1.0)
    let float_volume = volume.float();
    println!("Float volume: {}", float_volume);

    // Save new volume
    PersistentVolume::save(0.75).await?; // 75%

    Ok(())
}
```

--------------------------------

### Handle UI State Updates with Rust

Source: https://context7.com/talwat/lowfi/llms.txt

Initialize and update UI state based on broadcast channel messages.

```rust
use lowfi::ui::{State, Update};
use lowfi::player::Current;
use std::sync::Arc;

// Create initial UI state
fn create_state(sink: Arc<rodio::Player>, list_name: String) -> State {
    State::initial(sink, list_name)
}

// UI updates are sent via broadcast channel
fn handle_update(state: &mut State, update: Update) {
    match update {
        Update::Track(current) => {
            state.current = current;
            match &state.current {
                Current::Loading(Some(progress)) => {
                    println!("Loading: {:.0}%", progress.get() * 100.0);
                }
                Current::Loading(None) => {
                    println!("Waiting...");
                }
                Current::Track(info) => {
                    println!("Now playing: {}", info.display);
                }
            }
        }
        Update::Bookmarked(bookmarked) => {
            state.bookmarked = bookmarked;
            println!("Bookmarked: {}", bookmarked);
        }
        Update::Volume => {
            println!("Volume changed: {:.0}%", state.sink.volume() * 100.0);
        }
        Update::Quit => {
            println!("Quitting...");
        }
    }
}
```

--------------------------------

### Set environment variables

Source: https://context7.com/talwat/lowfi/llms.txt

Configure advanced runtime options like MPRIS naming and UI suppression.

```sh
# Limit MPRIS instances to one with fixed name "lowfi"
export LOWFI_FIXED_MPRIS_NAME=1
lowfi

# Disable UI completely (requires MPRIS for control)
export LOWFI_DISABLE_UI=1
lowfi
```

--------------------------------

### Player Module API

Source: https://context7.com/talwat/lowfi/llms.txt

Manages playback state and coordinates all subsystems.

```APIDOC
## Player Module API

### Description
Manages playback state and coordinates all subsystems.

### Initialization and Lifecycle
```rust
use lowfi::player::{Player, Current};
use lowfi::Args;

async fn example() -> lowfi::Result<()> {
    let args = Args::parse();
    let stream = lowfi::audio::stream()?;

    // Initialize player with args and audio mixer
    let (mut player, tasks) = Player::init(args, stream.mixer()).await?;

    // Run the main event loop
    tokio::select! {
        r = player.run() => r,
        r = tasks => r,
    }?;

    // Cleanup and persist state (volume, bookmarks)
    player.close().await?;
    Ok(())
}
```

### Player Messages Handled Internally
- **Message::Next / Message::Init / Message::Loaded**: Skip/load tracks
- **Message::Play / Message::Pause / Message::PlayPause**: Control playback
- **Message::ChangeVolume(f32)**: Adjust volume by delta
- **Message::SetVolume(f32)**: Set absolute volume (0.0 to 1.0)
- **Message::Bookmark**: Toggle bookmark on current track
- **Message::Quit**: Exit the player
```

--------------------------------

### Download List with Custom Track Names

Source: https://github.com/talwat/lowfi/blob/main/README.md

Allows specifying a custom display name for a downloaded track by appending '!custom name' after the track URL. The download still uses the original URL.

```txt
2023/04/2-In-Front-Of-Me.mp3!custom name
```

--------------------------------

### Download List with No Header

Source: https://github.com/talwat/lowfi/blob/main/README.md

If all tracks include their own protocol (e.g., 'https://'), you can use 'noheader' as the first line to prevent any base URL from being prepended.

```txt
noheader
https://example.com/track1.mp3
https://example.com/track2.mp3
```

--------------------------------

### Define custom track list formats

Source: https://context7.com/talwat/lowfi/llms.txt

Track lists use a base URL header followed by paths, optionally including custom display names.

```txt
https://example.com/music/
track1.mp3
subfolder/track2.mp3
2023/06/My-Song.mp3!My Custom Song Name
https://other-source.com/direct-link.mp3
```

```txt
file:///home/user/Music/lofi/
chill-beat.mp3
ambient-rain.mp3!Rainy Day Vibes
file:///home/user/Other/special-track.mp3
```

```txt
noheader
https://example.com/full/path/to/track1.mp3
https://another-site.com/music/track2.mp3!Custom Name
file:///home/user/Music/local-track.mp3
```

--------------------------------

### Send Player Commands with Rust

Source: https://context7.com/talwat/lowfi/llms.txt

Control playback, volume, and bookmarks by sending messages through an mpsc channel.

```rust
use lowfi::Message;
use tokio::sync::mpsc;

async fn send_commands(tx: mpsc::Sender<Message>) -> Result<(), Box<dyn std::error::Error>> {
    // Skip to next track
    tx.send(Message::Next).await?;

    // Pause playback
    tx.send(Message::Pause).await?;

    // Resume playback
    tx.send(Message::Play).await?;

    // Toggle play/pause
    tx.send(Message::PlayPause).await?;

    // Increase volume by 10%
    tx.send(Message::ChangeVolume(0.1)).await?;

    // Decrease volume by 10%
    tx.send(Message::ChangeVolume(-0.1)).await?;

    // Set volume to 50%
    tx.send(Message::SetVolume(0.5)).await?;

    // Bookmark current track
    tx.send(Message::Bookmark).await?;

    // Quit the player
    tx.send(Message::Quit).await?;

    Ok(())
}
```

--------------------------------

### Downloader API

Source: https://context7.com/talwat/lowfi/llms.txt

Download and queue tracks with progress tracking.

```APIDOC
## Downloader API

### Description
Download and queue tracks with progress tracking.

### Handling Track Downloads
```rust
use lowfi::downloader::{Progress, Output, Handle};
use lowfi::tracks::List;

// The downloader runs as a background task and fills a queue
// Access it through the Handle returned by Tasks::downloader()

fn handle_track(handle: &mut Handle) {
    match handle.track() {
        Output::Queued(queued) => {
            // Track is ready to play
            println!("Track ready: {}", queued.display);
            println!("Path: {}", queued.path);
            println!("Data size: {} bytes", queued.data.len());

            // Decode and play
            let decoded = queued.decode().expect("decode failed");
            println!("Duration: {:?}", decoded.info.duration);
        }
        Output::Loading(Some(progress)) => {
            // Download in progress
            let percent = progress.get() * 100.0;
            println!("Downloading: {:.1}%", percent);
        }
        Output::Loading(None) => {
            println!("Waiting for download to start...");
        }
    }
}
```
```

--------------------------------

### Track List API

Source: https://context7.com/talwat/lowfi/llms.txt

Load and manage track lists programmatically.

```APIDOC
## Track List API

### Description
Load and manage track lists programmatically.

### Loading Tracks
```rust
use lowfi::tracks::List;

async fn example() -> lowfi::tracks::Result<()> {
    // Load the default embedded chillhop list
    let list = List::load("chillhop").await?;

    // Load from data directory (e.g., ~/.local/share/lowfi/mytracks.txt)
    let list = List::load("mytracks").await?;

    // Load from absolute path
    let list = List::load("/home/user/Music/custom.txt").await?;

    // Access list properties
    println!("List name: {}", list.name);
    println!("Base URL: {}", list.header());
    println!("Track count: {}", list.lines.len() - 1);

    // Get a random track path and optional custom name
    let mut rng = fastrand::Rng::new();
    let (path, display_name) = list.random_path(&mut rng);
    println!("Random track: {}", path);
    if let Some(name) = display_name {
        println!("Display name: {}", name);
    }

    Ok(())
}
```

### Creating a List Programmatically
```rust
use lowfi::tracks::List;

fn create_list() -> List {
    let content = r###"https://example.com/music/
track1.mp3
track2.mp3!Custom Name
https://other.com/direct.mp3"###;

    List::new("my-list", content, None)
}
```
```

--------------------------------

### Track Structs

Source: https://context7.com/talwat/lowfi/llms.txt

Work with track data at different stages of processing.

```APIDOC
## Track Structs

### Description
Work with track data at different stages of processing.

### Queued Track Processing
```rust
use lowfi::tracks::{Queued, Decoded, Info};
use bytes::Bytes;

// Queued: Downloaded but not decoded
fn process_queued(queued: Queued) -> lowfi::tracks::Result<()> {
    println!("Track: {}", queued.display);
    println!("Path: {}", queued.path);
    println!("Raw data: {} bytes", queued.data.len());

    // Decode the track for playback
    let decoded = queued.decode()?;
    play_decoded(decoded);
    Ok(())
}
```

### Decoded Track Playback
```rust
use lowfi::tracks::{Queued, Decoded, Info};
use bytes::Bytes;

// Decoded: Ready for playback with full metadata
fn play_decoded(decoded: Decoded) {
    let info = &decoded.info;
    println!("Playing: {}", info.display);
    println!("Path: {}", info.path);
    println!("Display width: {} chars", info.width);

    if let Some(duration) = info.duration {
        println!("Duration: {:?}", duration);
    }

    // Convert back to track list entry format
    let entry = info.to_entry();
    println!("Entry format: {}", entry);
    // Output: "path/to/track.mp3!Display Name"
}
```

### Creating a Queued Track Manually
```rust
use lowfi::tracks::{Queued, Decoded, Info};
use bytes::Bytes;

// Create a queued track manually
fn create_queued(path: String, data: Bytes) -> lowfi::tracks::Result<Queued> {
    // Auto-format display name from path
    Queued::new(path.clone(), data.clone(), None)?;

    // Or specify custom display name
    Queued::new(path, data, Some("My Custom Track".to_string()))
}
```
```
Tokens:
Raw