docs: add section about bookmarks

this was a one line fix that i just completely forgot about whilst improving the bookmarking system.
i feel very, very stupid.

.gitignore

@@ -1 +1,3 @@
 /target
+/cache
+.DS_Store

CHILLHOP.md

@@ -0,0 +1,29 @@
+# Using the chillhop list
+
+> [!WARNING]
+> As of lowfi 1.7.0, the chillhop list is included by default. For a more
+> detailed explanation, see [MUSIC.md](MUSIC.md). This document is included
+> to preserve any old links or references. The instructions are still valid.
+
+## Linux
+
+```sh
+mkdir -p ~/.local/share/lowfi
+curl https://raw.githubusercontent.com/talwat/lowfi/refs/heads/main/data/chillhop.txt -O --output-dir ~/.local/share/lowfi
+```
+
+## MacOS
+
+```sh
+mkdir -p "$HOME/Library/Application Support/lowfi"
+curl https://raw.githubusercontent.com/talwat/lowfi/refs/heads/main/data/chillhop.txt -O --output-dir "$HOME/Library/Application Support/lowfi"
+```
+
+## Windows
+
+Go to `%appdata%` in Explorer, then `Roaming`, and make a folder called `lowfi`.
+Then just put [this file](https://raw.githubusercontent.com/talwat/lowfi/refs/heads/main/data/chillhop.txt) in there.
+
+## Launching lowfi
+
+Once the list has been added, just launch `lowfi` with `-t chillhop`.

CONTRIBUTING.md

@@ -0,0 +1,26 @@
+# Contributing to lowfi
+
+There are a few guidelines outlined here that will make it more likely for your PR to be accepted.
+Only ones that are less obvious are going to be listed. If you need to ask, it's probably a no.
+
+## 1. No AI
+
+You can use AI for searching and so on, and if there's something minor and tedious that you'd like
+the AI to write then that's okay, but if it is noticable that you used AI then it is way too much.
+If you used AI, you aren't helping any maintainer by submitting your slop, it's just a hassle for them.
+
+## 2. Smaller is better
+
+Try and make it so that each PR is one contained feature. Adding multiple features in a PR is usually a bad idea.
+This is also so that individual features can be approved or denied, rather than that having to be for a more significant
+chunk of code.
+
+## 3. Keep lowfi simple
+
+lowfi is supposed simple program. For now, no changes to the initial user-facing UI will be accepted.
+The UI of lowfi playing a song has stayed identical since the first versions, since complicating it
+detracts from it's purpose.
+
+More complex features, like fancy colors or cover art, will not be accepted ever. Implementations of
+acceptable features should also be simple and not too obtrusive. Even if a feature is simple,
+if it is very complex to implement, then it won't be accepted.

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "lowfi"
-version = "1.6.2-dev"
+version = "1.7.2"
 edition = "2021"
 description = "An extremely simple lofi player."
 license = "MIT"
@@ -18,36 +18,47 @@ repository = "https://github.com/talwat/lowfi"
 
 [features]
 mpris = ["dep:mpris-server"]
+extra-audio-formats = ["rodio/default"]
+scrape = ["dep:serde", "dep:serde_json", "dep:html-escape", "dep:scraper", "dep:indicatif"]
 
 [dependencies]
 # Basics
 clap = { version = "4.5.21", features = ["derive", "cargo"] }
-eyre = { version = "0.6.12" }
+eyre = "0.6.12"
-rand = "0.8.5"
+fastrand = "2.3.0"
+thiserror = "2.0.12"
+color-eyre = { version = "0.6.5", default-features = false }
 
 # Async
-tokio = { version = "1.41.1", features = [
+tokio = { version = "1.41.1", features = ["macros", "rt-multi-thread", "fs"], default-features = false }
-    "macros",
-    "rt-multi-thread",
-    "fs"
-], default-features = false }
 futures = "0.3.31"
 arc-swap = "1.7.1"
 
 # Data
-reqwest = "0.12.9"
+reqwest = { version = "0.12.9", features = ["stream"] }
 bytes = "1.9.0"
 
 # I/O
-crossterm = { version = "0.28.1", features = ["event-stream"] }
+crossterm = { version = "0.29.0", features = ["event-stream"] }
-rodio = { version = "0.20.1", features = ["symphonia-mp3"], default-features = false }
+rodio = { version = "0.21.1", features = ["symphonia-mp3", "playback"], default-features = false }
 mpris-server = { version = "0.8.1", optional = true }
-dirs = "5.0.1"
+dirs = "6.0.0"
 
 # Misc
-scraper = "0.21.0"
+convert_case = "0.8.0"
-Inflector = "0.11.4"
 lazy_static = "1.5.0"
-libc = "0.2.167"
 url = "2.5.4"
 unicode-segmentation = "1.12.0"
+
+# Scraper
+serde = { version = "1.0.219", features = ["derive"], optional = true }
+serde_json = { version = "1.0.142", optional = true }
+scraper = { version = "0.21.0", optional = true }
+html-escape = { version = "0.2.13", optional = true }
+indicatif = { version = "0.18.0", optional = true }
+regex = "1.11.1"
+atomic_float = "1.1.0"
+
+[target.'cfg(target_os = "linux")'.dependencies]
+libc = "0.2.167"
+

ENVIRONMENT_VARS.md

@@ -0,0 +1,7 @@
+# Environment Variables
+
+Lowfi has some more specific options, usually as a result of minor feature requests, which are only documented here.
+If you have some behaviour you'd like to change, which is quite specific, then see if one of these options suits you.
+
+* `LOWFI_FIXED_MPRIS_NAME` - Limits the number of lowfi instances to one, but ensures the player name is always `lowfi`.
+* `LOWFI_DISABLE_UI` - Disables the UI.

MUSIC.md

@@ -0,0 +1,75 @@
+# The State of Lowfi's Music
+
+> [!WARNING]
+> This document will be a bit long and has almost nothing to do with the actual
+> usage of lowfi, just the music embedded by default.
+
+Before that though, some context. lowfi includes an extensive track list
+embedded into the software, so you can download it and have it "just work"
+out of the box.
+
+I always hated apps that required extensive configuration just to be usable.
+Sometimes it's justified, but often, it's just pointless when most will end up
+with the same set of "defaults" that aren't really defaults.
+
+Lowfi is so nice and simple because of the "plug and play" aspect,
+but it's become a lot harder to continue it as of late.
+
+## The Lofi Girl List
+
+Originally, it was planned that lowfi would use music scraped from Lofi Girl's own
+website. The scraper actually came before the rest of the program, believe it or not.
+
+However, after a long period of downtime, the Lofi Girl website was redone without the
+mp3 track files. Those are now pretty much inaccessible aside from paying for individual
+albums on bandcamp which gets very expensive very quickly.
+
+Doing this was never actually disallowed, but it is now simply impossible. So, the question was,
+what to do next after losing lowfi's primary source of music?
+
+## Tracklists
+
+I was originally against the idea of custom tracklists, because of my almost purist
+ideals of a 100% no config at all vision for lowfi. But eventually, I gave in, which proved
+to be a very good decision in hindsight. Now, regardless of what choices I make on the music
+which is embedded, all may opt out of that and choose whatever they like.
+
+This culminated in a few templates located in the `data` directory of this repository
+which included a handful of tracklists, and in particular, the chillhop list by user
+[danielwerg](https://github.com/danielwerg).
+
+## The Switch
+
+After `lofigirl.com` went down, I thought a bit and eventually decided
+to just bite the bullet and switch to the chillhop list. This was despite the fact
+that chillhop entirely bans third party players in their TOS. They also ban
+scrapers, which I only learned after writing one.
+
+So, is lowfi really going to have to violate the TOS of it's own music provider?
+Well, yes. I thought about it, and came to the conclusion that lowfi is probably
+not much of a threat for a few reasons.
+
+Firstly, it emulates exactly the behavior of chillhop's own radio player.
+The only difference is that one shoves you into a web browser, and the other,
+into a nice terminal window.
+
+Then, I also realize that lowfi is just a small program used by few.
+I'm not making money on any of this, and I think degrading the experience for my
+fellow nerds who just want to listen to some lowfi without all the crap is not worth it.
+
+At the end of the day, lowfi has a distinct UserAgent. Should chillhop ever take issue with
+it's behaviour, banning it is extremely simple. I don't want that to happen, but I
+understand if it does.
+
+## Well, *I* Hate the Chillhop Music
+
+It's not as "lofi". It is almost certainly a compromise, that much I cannot even pretend to
+deny. I find myself hitting the skip button almost three times as often with chillhop.
+
+If you are undeterred enough by TOS's to read this far, then you can use the `archive.txt`
+list in the `data` folder. The list is a product of me worrying that the tracks on `lofigirl.com`
+could've possibly been lost somehow, relating to the website going down.
+
+It's hosted on `archive.org`, and could be taken down at any point for any reason.
+Being derived from my own local archive, it retains ~2700 out of the ~3700 tracks.
+That's not perfect, the organization is also *bad*, but it exists.

README.md

@@ -7,24 +7,18 @@ It'll do this as simply as it can: no albums, no ads, just lofi.
 
 ## Disclaimer
 
-**All** of the audio files played in lowfi are from [Lofi Girl's](https://lofigirl.com/) website,
+As of the 1.7.0 version of lowfi, **all** of the audio files embedded
-under their [licensing guidelines](https://form.lofigirl.com/CommercialLicense).
+by default are from [chillhop](https://chillhop.com/). Read
-
+[MUSIC.md](MUSIC.md) for more information.
-If god forbid you're planning to use this in a commercial setting, please
-follow their rules.
 
 ## Why?
 
-I really hate modern music platforms, and I wanted a small, "suckless"
+I really hate modern music platforms, and I wanted a small, simple  
-app that would just play random lofi without video.
+app that would just play random ambient music without video and other fluff.
 
-It was also designed to be fairly resilient to inconsistent networks,
+Beyond that, it was also designed to be fairly resilient to inconsistent networks,
 and as such it buffers 5 whole songs at a time instead of parts of the same song.
 
-Although, lowfi is yet to be properly tested in difficult conditions,
-so don't rely on it too much until I do that. See [Scraping](#scraping) if
-you're interested in downloading the tracks. Beware, there's a lot of them.
-
 ## Installing
 
 > [!NOTE]
@@ -40,8 +34,8 @@ On MacOS & Windows, no extra dependencies are needed.
 
 On Linux, you'll also need openssl & alsa, as well as their headers.
 
-- `alsa-lib` on Arch, `libasound2-dev` on Ubuntu.
+- `alsa-lib` on Arch, `libasound2-dev` on Ubuntu, `alsa-lib-devel` on Fedora.
-- `openssl` on Arch, `libssl-dev` on Ubuntu.
+- `openssl` on Arch, `libssl-dev` on Ubuntu, `openssl-devel` on Fedora.
 
 Make sure to also install `pulseaudio-alsa` if you're using PulseAudio.
 
@@ -57,16 +51,15 @@ cargo install lowfi --features mpris
 ```
 
 and making sure `$HOME/.cargo/bin` is added to `$PATH`.
+Also see [Extra Features](#extra-features) for extended functionality.
 
 ### Release Binaries
 
-If you're struggling or unwilling to use cargo, you can just download
+If you're struggling or unwilling to use cargo, you can just download the
 precompiled binaries from the [latest release](https://github.com/talwat/lowfi/releases/latest).
 
 ### AUR
 
-If you're on Arch, you can also use the AUR:
-
 ```sh
 yay -S lowfi
 ```
@@ -77,6 +70,27 @@ yay -S lowfi
 zypper install lowfi
 ```
 
+### Debian
+
+> [!NOTE]
+> This uses an unofficial Debian repository maintained by [Dario Griffo](https://github.com/dariogriffo).
+
+```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
+```
+
+### Fedora (COPR)
+
+> [!NOTE]
+> This uses an unofficial COPR repository by [FurqanHun](https://github.com/FurqanHun).
+
+```sh
+sudo dnf copr enable furqanhun/lowfi
+sudo dnf install lowfi
+```
+
 ### Manual
 
 This is good for debugging, especially in issues.
@@ -110,76 +124,110 @@ Yeah, that's it.
 | `-`, `_`, `j`, `↓` | Volume Down 10% |
 | `←`                | Volume Down 1%  |
 | `q`, CTRL+C        | Quit            |
+| `b`                | Bookmark        |
 
 > [!NOTE]
 > Besides its regular controls, lowfi offers compatibility with Media Keys
-> and [MPRIS](https://wiki.archlinux.org/title/MPRIS) (with tools like `playerctl`)
+> and [MPRIS](https://wiki.archlinux.org/title/MPRIS) (with tools like `playerctl`).
 >
-> MPRIS is currently optional feature in cargo (enabled with `--features mpris`)
+> MPRIS is currently an [optional feature](#extra-features) in cargo (enabled with `--features mpris`)
 > due to it being only for Linux, as well as the fact that the main point of
 > lowfi is it's unique & minimal interface.
 
+### Bookmarks
+
+Bookmarks are lowfi's extremely simple answer to "what about if I'd like to save a track."
+You can bookmark/unbookmark tracks with `b`, and play them with `lowfi -t bookmarks`.
+
+From a technical perspective, your bookmarks are no different to any other track list,
+and as such are also stored in the same directory.
+
 ### Extra Flags
 
 If you have something you'd like to tweak about lowfi, you use additional flags which
-slightly tweak the UI or behaviour of the menu. The flags can be viewed with `lowfi help`.
+slightly tweak the UI or behaviour of the menu. The flags can be viewed with `lowfi --help`.
 
-| Flag                            | Function                                       |
+| Flag                                | Function                                            |
-| ------------------------------- | ---------------------------------------------- |
+| ----------------------------------- | --------------------------------------------------- |
-| `-a`, `--alternate`             | Use an alternate terminal screen               |
+| `-a`, `--alternate`                 | Use an alternate terminal screen                    |
-| `-m`, `--minimalist`            | Hide the bottom control bar                    |
+| `-m`, `--minimalist`                | Hide the bottom control bar                         |
-| `-b`, `--borderless`            | Exclude borders in UI                          |
+| `-b`, `--borderless`                | Exclude borders in UI                               |
-| `-p`, `--paused`                | Start lowfi paused                             |
+| `-p`, `--paused`                    | Start lowfi paused                                  |
-| `-d`, `--debug`                 | Include ALSA & other logs                      |
+| `-f`, `--fps`                       | FPS of the UI [default: 12]                         |
-| `-w`, `--width <WIDTH>`         | Width of the player, from 0 to 32 [default: 3] |
+| `--timeout`                         | Timeout in seconds for music downloads [default: 3] |
-| `-t`, `--tracklist <TRACKLIST>` | Use a [custom track list](#custom-track-lists) |
+| `-d`, `--debug`                     | Include ALSA & other logs                           |
+| `-w`, `--width <WIDTH>`             | Width of the player, from 0 to 32 [default: 3]      |
+| `-t`, `--track-list <TRACK_LIST>`   | Use a [custom track list](#custom-track-lists)      |
+| `-s`, `--buffer-size <BUFFER_SIZE>` | Internal song buffer size [default: 5]              |
 
-### Scraping
+### Extra Features
 
-lowfi also has a `scrape` command which is usually not relevant, but
+lowfi uses cargo/rust's "feature" system to make certain parts of the program optional,
-if you're trying to download some files from Lofi Girls' website,
+like those which are only expected to be used by a handful of users.
-it can be useful.
 
-An example of scrape is as follows,
+#### `scrape` - Scraping
 
-`lowfi scrape --extension zip --include-full`
+This feature provides the `scrape` command.
+It's usually not very useful, but is included for transparency's sake.
 
-where more information can be found by running `lowfi help scrape`.
+More information can be found by running `lowfi help scrape`.
+
+#### `mpris` - MPRIS
+
+Enables MPRIS. It's not rocket science.
+
+#### `extra-audio-formats` - Extra Audio Formats
+
+This is only relevant to those using a custom track list, in which case
+it allows for more formats than just MP3. Those are FLAC, Vorbis, and WAV.
+
+These should be sufficient for some 99% of music files people might want to play.
+If you are dealing with the 1% using another audio format which is in
+[this list](https://github.com/pdeljanov/Symphonia?tab=readme-ov-file#codecs-decoders), open an issue.
 
 ### Custom Track Lists
 
-> [!WARNING]
+> [!NOTE]
+> Some nice users, especially [danielwerg](https://github.com/danielwerg),
+> have aleady made alternative track lists located in the [data](https://github.com/talwat/lowfi/blob/main/data/)
+> directory of this repo. You can use them with lowfi by using the `--track-list` flag.
 >
-> Custom track lists are going to be pretty particular.
+> Feel free to contribute your own list with a PR.
-> This is because I still want to keep `lowfi` as simple as possible,
-> so custom lists will be very similar to how the built in list functions.
->
-> This also means that there will be no added flexibility to these lists,
-> so you'll have to work that out on your own.
 
-lowfi also supports custom track lists, although the default one from Lofi Girl
+lowfi also supports custom track lists, although the default one from chillhop
 is embedded into the binary.
 
-To use a custom list, use the `--tracks` flag. This can either be a path to some file,
+To use a custom list, use the `--track-list` flag. This can either be a path to some file,
 or it could also be the name of a file (without the `.txt` extension) in the data
-directory, so on Linux it's `~/.local/share/lowfi`.
+directory.
 
-For example, `lowfi --tracks minipop` would load `~/.local/share/lowfi/minipop.txt`.
+> [!NOTE]
-Whereas if you did `lowfi --tracks ~/Music/minipop.txt` it would load from that
+> Data directories:
+>
+> - Linux - `~/.local/share/lowfi`
+> - macOS - `~/Library/Application Support/lowfi`
+> - Windows - `%appdata%\Roaming\lowfi`
+
+For example, `lowfi --track-list minipop` would load `~/.local/share/lowfi/minipop.txt`.
+Whereas if you did `lowfi --track-list ~/Music/minipop.txt` it would load from that
 specified directory.
 
+All tracks must be in the MP3 format, unless lowfi has been compiled with the
+`extra-audio-formats` feature which includes support for some others.
+
 #### The Format
 
-In lists, the first line should be the base URL, followed by the rest of the tracks.
+In lists, the first line is what's known as the header, followed by the rest of the tracks.
-This is also known as the "header", because it comes first.
+Each track will be first appended to the header, and then use the combination to download
+the track.
 
-Each track will be first appended to the base URL, and then the result use to download
+> [!NOTE]
-the track. All tracks must be in the MP3 format, as lowfi doesn't support any others currently.
+> lowfi _will not_ put a `/` between the base & track for added flexibility,
+> so for most cases you should have a trailing `/` in your header.
 
-Additionally, lowfi _won't_ put a `/` between the base & track for added flexibility,
+The exception to this is if the track name begins with a protocol like `https://`,
-so for most cases you should have a trailing `/` in your base url.
+in which case the base will not be prepended to it. If all of your tracks are like this,
-The exception to this is if the track name begins with something like `https://`,
+then you can put `noheader` as the first line and not have a header at all.
-where in that case the base will not be prepended to it.
 
 For example, in this list:
 
@@ -187,13 +235,13 @@ For example, in this list:
 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/fea570b16e6703ef79e65b4/2017/11/file_example_MP3_5MG.mp3
+https://file-examples.com/storage/fe85f7a43b689349d9c8f18/2017/11/file_example_MP3_1MG.mp3
 ```
 
 lowfi would download these three URLs:
 
 - `https://lofigirl.com/wp-content/uploads/2023/06/Foudroie-Finding-The-Edge-V2.mp3`
-- `https://file-examples.com/storage/fea570b16e6703ef79e65b4/2017/11/file_example_MP3_5MG.mp3`
+- `https://file-examples.com/storage/fe85f7a43b689349d9c8f18/2017/11/file_example_MP3_1MG.mp3`
 - `https://lofigirl.com/wp-content/uploads/2023/04/2-In-Front-Of-Me.mp3`
 
 Additionally, you may also specify a custom display name for the track which is indicated by a `!`.
@@ -204,3 +252,14 @@ For example, if you had an entry like this:
 ```
 
 Then lowfi would download from the first section, and display the second as the track name.
+
+`file://` can be used in front a track/header to make lowfi treat it as a local file.
+This is useful if you want to use a local file as the base URL, for example:
+
+```txt
+file:///home/user/Music/
+file.mp3
+file:///home/user/Other Music/second-file.mp3
+```
+
+Further examples can be found in the [data](https://github.com/talwat/lowfi/tree/main/data) folder.

data/file.txt

@@ -1,2 +1,2 @@
 file:///home/user/Music/
-Anomaly.mp3
+Test.mp3

data/micropop.txt

@@ -1,16 +0,0 @@
-https://archive.org/download/jack-stauber-s-micropop-extended-micropops/Jack%20Stauber-%27s%20Micropop%20-%20
-Al%20Dente.mp3
-Baby%20Hotline.mp3
-Cupid.mp3
-Deploy.mp3
-Dinner%20Is%20Not%20Over.mp3
-Fighter.mp3
-Inchman.mp3
-Keyman.mp3
-Out%20the%20Ox.mp3
-Tea%20Errors.mp3
-The%20Ballad%20of%20Hamantha.mp3
-There%27s%20Something%20Happening.mp3
-Those%20Eggs%20Aren%27t%20Dippy%20.mp3
-Today%20Today.mp3
-Two%20Time.mp3

data/noheader.txt

@@ -0,0 +1,2 @@
+noheader
+https://stream.chillhop.com/mp3/9476

data/old/synthboy.txt

@@ -0,0 +1,115 @@
+https://lofigirl.com/wp-content/uploads/
+2024/01/1.-i_m-alone-out-here-ft.-Outgrown-master.mp3
+2024/01/2.-aurora-ft.-Outgrown-master.mp3
+2024/01/3.-dusk-master.mp3
+2024/01/4.-aria-ft.-after-noon-master.mp3
+2024/01/5.-dreamscape-ft.-Luke-Tidbury-master.mp3
+2023/11/Le-Metroid-Crystal-Children.mp3
+2023/11/Le-Metroid-Frequencies.mp3
+2023/11/Le-Metroid-Space-Echoes.mp3
+2023/11/Le-Metroid-Voyager.mp3
+2023/11/Le-Metroid-Orion.mp3
+2023/11/Le-Metroid-Saturne.mp3
+2023/11/Le-Metroid-Speed-Light.wav
+2023/11/Le-Metroid-Earth-21.wav
+2023/11/Le-Metroid-Sleepwalker.mp3
+2023/11/Le-Metroid-Blackhole.mp3
+2023/09/01-Akraa-Lightyears-Kupla-master.mp3
+2023/09/02-Virtua-_-Robert-Iver-Analogue-Pulsar-Kupla-master.mp3
+2023/09/03-Starwave-Soundgo-Kupla-Master.mp3
+2023/09/04-Forhill-_-Eagle-Eyed-Tiger-Infuse-Kupla-Master.mp3
+2023/09/05-VIQ-x-Krosia-Echodrift-Kupla-Master.mp3
+2023/09/06-Tbeauthetraveler-Soare-Kupla-master.mp3
+2023/09/07-Boy-From-Nowhere-Bleue-Astrale-Kupla-Master-.mp3
+2023/09/08-Virtua-Searching-Kupla-Master.mp3
+2023/09/09-Electrosky-Soundgo-Kupla-Master.mp3
+2023/09/10-Protocols-Orion-Kupla-Master.mp3
+2023/09/11-Hotel_Pools_Satin_Kupla-Master.mp3
+2023/09/12-Downtown-Binary-Icarus-Kupla-Master.mp3
+2023/09/13-A.L.I.S.O.N-Erebus-Kupla-Master.mp3
+2023/09/14-Girl-From-Nowhere-x-Boy-From-Nowhere-Diamond-Kupla-Master.mp3
+2023/09/15-Kabes-x-Protocols-Static-Kupla-Master.mp3
+2023/09/16-VIQ-Somewhere-Kupla-Master.mp3
+2023/09/17-Akraa-Virtua-Portal-Kupla-Master-2.mp3
+2023/09/18-Nitewalk-x-SwuM-Last-Cosmo-Kupla-Master.mp3
+2023/09/19-Nitewalk-Prismatic-Waves-Kupla-Master3.mp3
+2023/09/20-Theo-Aabel-Night-Owl-Kupla-Master.mp3
+2023/06/Foudroie-Journey-2023.mp3
+2023/06/Foudroie-Odyssey-MASTER.mp3
+2023/06/Foudroie-Solar-Wind-MASTER.mp3
+2023/06/Foudroie-x-Forhill-Interstellar-MASTER.mp3
+2023/06/Foudroie-The-Traveler-2023.mp3
+2023/06/Foudroie-Moon-Dust-2023.mp3
+2023/06/Foudroie-Departure-2023.mp3
+2023/06/Foudroie-Interpolation-2023.mp3
+2023/06/Foudroie-Lunar-2023.mp3
+2023/06/Foudroie-Finding-The-Edge-V2.mp3
+2023/06/A1Descend.mp3
+2023/06/A3S.O.L.O.mp3
+2023/06/B4K.E.Y.S.mp3
+2023/06/EmilRottmayerW.A.V.E.mp3
+2023/06/EmilRottmayerMEGA.mp3
+2023/06/1.-steezy-prime-better-days-w_-devon-rea-_-fnonose.mp3
+2023/06/2.-steezy-prime-deep-thoughts-w_-beyond-pluto.mp3
+2023/06/3.-steezy-prime-in-the-air.mp3
+2023/06/4.-steezy-prime-gemini-w_-laffey.mp3
+2023/06/5.-steezy-prime-it_s-getting-late-w_-mildred-_-devon-rea.mp3
+2023/06/6.-steezy-prime-slow-blink-w_-fnonose.mp3
+2023/05/Polaris.mp3
+2023/05/Taking-Flight.mp3
+2023/05/Astral.mp3
+2023/05/Atlantis.mp3
+2023/05/Cirrus.mp3
+2023/05/Light-Cycles.mp3
+2023/05/Umbra.mp3
+2023/05/Shuto-Expressway.mp3
+2023/05/Fantasia.mp3
+2023/05/Winter.mp3
+2023/05/Pandora.mp3
+2023/05/4am.mp3
+2023/05/Aurora.mp3
+2023/05/Lost-Signal.mp3
+2023/05/Reflect.mp3
+2023/05/City-Lights.mp3
+2023/05/Pools.mp3
+2023/05/Void.mp3
+2023/05/Distant.mp3
+2023/05/1.-Voyage-Beyond.mp3
+2023/05/2.-A.L.I.S.O.N-always-in-my-dreams.mp3
+2023/05/3.Hotel-Pools-Limits.mp3
+2023/05/4.-Downtown-Binary-Atlantis.mp3
+2023/05/5.-Voyage-Moon-Phase.mp3
+2023/05/6.Downtown-Binary-_-The-Present-Sound-Polaris.mp3
+2023/05/7.-Hotel-Pools-_-A.L.I.S.O.N_Lunar.mp3
+2023/05/8.Hotel-Pools-Snowfall.mp3
+2023/05/9.-oDDling-Drifting.mp3
+2023/05/10.-Hotel-Pools-_-oDDling-Remain.mp3
+2023/05/11.-A.L.I.S.O.N-Subtract.mp3
+2023/05/13.-oDDling-Void.mp3
+2023/05/14.-EmilRottmayer-Elevate.mp3
+2023/05/15.-Transparent-transparent.mp3
+2023/05/16.-Neon-Galaxy-Portal.mp3
+2023/05/17.-KING-PALM-Luxury.mp3
+2023/05/18.-Departure-Imagine.mp3
+2023/05/19.-Voyage-Center-Point.mp3
+2023/05/20.-A.L.I.S.O.N-Nightride-Revisited.mp3
+2023/05/21.-VIQ-Orbit.mp3
+2023/05/22.-KING-PALM-Journey.mp3
+2023/05/23.-Krosia-Crystal-Bells.mp3
+2023/05/24.-EVANS-third-planet.mp3
+2023/05/25.-Hotel-Pools-Evolve.mp3
+2023/05/26.-KING-PALM-Coast.mp3
+2023/05/27.-Monolism-infinitespace.mp3
+2023/05/28.-oDDling-Divide.mp3
+2023/05/29.-GRAEDA-Deluge.mp3
+2023/05/30.-Xtract-Audiotool-Day-2016.mp3
+2023/05/31.-MEGAS-Stargazer.mp3
+2023/05/32.-Hotel-Pools-_-Forhill-Descent.mp3
+2023/05/33.-Hotel-Pool-_-Memorex-Memories-Distance.mp3
+2023/05/34.-GRAEDA-Barranca.mp3
+2023/05/35.-Davz-Mindless.mp3
+2023/05/36.-Unfound-Rise.mp3
+2023/05/37.-oDDling-Reverie.mp3
+2023/05/38.-Unfound-Heaven.mp3
+2023/05/39.-Novus-Sana-Sound-of-the-Sky.mp3
+2023/05/40.-Krosia-Sonar.mp3

data/sample.txt

@@ -1,4 +1,4 @@
 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/fea570b16e6703ef79e65b4/2017/11/file_example_MP3_5MG.mp3
+https://stream.chillhop.com/mp3/9476

scripts/fix_cache.sh

@@ -0,0 +1,4 @@
+#!/bin/sh
+
+grep -rlZ "429 Too Many Requests" . | xargs -0 rm -f
+find . -type f -empty -delete

src/main.rs

@@ -3,21 +3,24 @@
 #![warn(clippy::all, clippy::pedantic, clippy::nursery)]
 
 use clap::{Parser, Subcommand};
+use std::path::PathBuf;
 
+mod messages;
 mod play;
 mod player;
 mod tracks;
 
 #[allow(clippy::all, clippy::pedantic, clippy::nursery, clippy::restriction)]
-mod scrape;
+#[cfg(feature = "scrape")]
+mod scrapers;
+
+#[cfg(feature = "scrape")]
+use crate::scrapers::Source;
 
 /// An extremely simple lofi player.
-#[derive(Parser)]
+#[derive(Parser, Clone)]
 #[command(about, version)]
-#[allow(
+#[allow(clippy::struct_excessive_bools)]
-    clippy::struct_excessive_bools,
-    reason = "señor clippy, i assure you this is not a state machine"
-)]
 struct Args {
     /// Use an alternate terminal screen.
     #[clap(long, short)]
@@ -35,6 +38,14 @@ struct Args {
     #[clap(long, short)]
     paused: bool,
 
+    /// FPS of the UI.
+    #[clap(long, short, default_value_t = 12)]
+    fps: u8,
+
+    /// Timeout in seconds for music downloads.
+    #[clap(long, default_value_t = 3)]
+    timeout: u64,
+
     /// Include ALSA & other logs.
     #[clap(long, short)]
     debug: bool,
@@ -44,8 +55,12 @@ struct Args {
     width: usize,
 
     /// Use a custom track list
-    #[clap(long, short, alias = "list", short_alias = 'l')]
+    #[clap(long, short, alias = "list", alias = "tracks", short_alias = 'l')]
-    tracklist: Option<String>,
+    track_list: Option<String>,
+
+    /// Internal song buffer size.
+    #[clap(long, short = 's', alias = "buffer", default_value_t = 5)]
+    buffer_size: usize,
 
     /// The command that was ran.
     /// This is [None] if no command was specified.
@@ -54,35 +69,43 @@ struct Args {
 }
 
 /// Defines all of the extra commands lowfi can run.
-#[derive(Subcommand)]
+#[derive(Subcommand, Clone)]
 enum Commands {
-    /// Scrapes the lofi girl website file server for files.
+    /// Scrapes a music source for files.
+    #[cfg(feature = "scrape")]
     Scrape {
-        /// The file extension to search for, defaults to mp3.
+        // The source to scrape from.
-        #[clap(long, short, default_value = "mp3")]
+        source: scrapers::Source,
-        extension: String,
-
-        /// Whether to include the full HTTP URL or just the distinguishing part.
-        #[clap(long, short)]
-        include_full: bool,
     },
 }
 
+/// Gets lowfi's data directory.
+pub fn data_dir() -> eyre::Result<PathBuf, player::Error> {
+    let dir = dirs::data_dir()
+        .ok_or(player::Error::DataDir)?
+        .join("lowfi");
+
+    Ok(dir)
+}
+
 #[tokio::main]
 async fn main() -> eyre::Result<()> {
-    #[cfg(target_os = "android")]
+    color_eyre::install()?;
-    compile_error!("Android Audio API not supported due to threading shenanigans");
 
     let cli = Args::parse();
 
     if let Some(command) = cli.command {
         match command {
-            Commands::Scrape {
+            #[cfg(feature = "scrape")]
-                extension,
+            Commands::Scrape { source } => match source {
-                include_full,
+                Source::Archive => scrapers::archive::scrape().await?,
-            } => scrape::scrape(extension, include_full).await,
+                Source::Lofigirl => scrapers::lofigirl::scrape().await?,
+                Source::Chillhop => scrapers::chillhop::scrape().await?,
+            },
         }
     } else {
-        play::play(cli).await
+        play::play(cli).await?;
-    }
+    };
+
+    Ok(())
 }

src/messages.rs

@@ -0,0 +1,37 @@
+/// Handles communication between the frontend & audio player.
+#[derive(PartialEq, Debug, Clone, Copy)]
+pub enum Message {
+    /// Notifies the audio server that it should update the track.
+    Next,
+
+    /// Special in that this isn't sent in a "client to server" sort of way,
+    /// but rather is sent by a child of the server when a song has not only
+    /// been requested but also downloaded aswell.
+    NewSong,
+
+    /// This signal is only sent if a track timed out. In that case,
+    /// lowfi will try again and again to retrieve the track.
+    TryAgain,
+
+    /// Similar to Next, but specific to the first track.
+    Init,
+
+    /// Unpause the [Sink].
+    #[allow(dead_code, reason = "this code may not be dead depending on features")]
+    Play,
+
+    /// Pauses the [Sink].
+    Pause,
+
+    /// Pauses the [Sink]. This will also unpause it if it is paused.
+    PlayPause,
+
+    /// Change the volume of playback.
+    ChangeVolume(f32),
+
+    /// Bookmark the current track.
+    Bookmark,
+
+    /// Quits gracefully.
+    Quit,
+}

src/play.rs

@@ -1,100 +1,42 @@
 //! Responsible for the basic initialization & shutdown of the audio server & frontend.
 
-use std::path::PathBuf;
+use crossterm::cursor::Show;
+use crossterm::event::PopKeyboardEnhancementFlags;
+use crossterm::terminal::{self, Clear, ClearType};
+use std::io::{stdout, IsTerminal};
+use std::process::exit;
 use std::sync::Arc;
-
+use std::{env, panic};
-use eyre::eyre;
-use tokio::fs;
 use tokio::{sync::mpsc, task};
 
+use crate::messages::Message;
+use crate::player::persistent_volume::PersistentVolume;
 use crate::player::Player;
-use crate::player::{ui, Messages};
+use crate::player::{self, ui};
 use crate::Args;
 
-/// This is the representation of the persistent volume,
-/// which is loaded at startup and saved on shutdown.
-#[derive(Clone, Copy)]
-pub struct PersistentVolume {
-    /// The volume, as a percentage.
-    inner: u16,
-}
-
-impl PersistentVolume {
-    /// Retrieves the config directory.
-    async fn config() -> eyre::Result<PathBuf> {
-        let config = dirs::config_dir()
-            .ok_or_else(|| eyre!("Couldn't find config directory"))?
-            .join(PathBuf::from("lowfi"));
-
-        if !config.exists() {
-            fs::create_dir_all(&config).await?;
-        }
-
-        Ok(config)
-    }
-
-    /// Returns the volume as a float from 0 to 1.
-    pub fn float(self) -> f32 {
-        f32::from(self.inner) / 100.0
-    }
-
-    /// Loads the [`PersistentVolume`] from [`dirs::config_dir()`].
-    pub async fn load() -> eyre::Result<Self> {
-        let config = Self::config().await?;
-        let volume = config.join(PathBuf::from("volume.txt"));
-
-        // Basically just read from the volume file if it exists, otherwise return 100.
-        let volume = if volume.exists() {
-            let contents = fs::read_to_string(volume).await?;
-            let trimmed = contents.trim();
-            let stripped = trimmed.strip_suffix("%").unwrap_or(trimmed);
-            stripped
-                .parse()
-                .map_err(|_error| eyre!("volume.txt file is invalid"))?
-        } else {
-            fs::write(&volume, "100").await?;
-            100u16
-        };
-
-        Ok(Self { inner: volume })
-    }
-
-    /// Saves `volume` to `volume.txt`.
-    pub async fn save(volume: f32) -> eyre::Result<()> {
-        let config = Self::config().await?;
-        let path = config.join(PathBuf::from("volume.txt"));
-
-        #[expect(
-            clippy::as_conversions,
-            clippy::cast_sign_loss,
-            clippy::cast_possible_truncation,
-            reason = "already rounded & absolute, therefore this should be safe"
-        )]
-        let percentage = (volume * 100.0).abs().round() as u16;
-
-        fs::write(path, percentage.to_string()).await?;
-
-        Ok(())
-    }
-}
-
-/// Wrapper around [`rodio::OutputStream`] to implement [Send], currently unsafely.
-///
-/// This is more of a temporary solution until cpal implements [Send] on it's output stream.
-pub struct SendableOutputStream(pub rodio::OutputStream);
-
-// SAFETY: This is necessary because [OutputStream] does not implement [Send],
-// due to some limitation with Android's Audio API.
-// I'm pretty sure nobody will use lowfi with android, so this is safe.
-#[expect(
-    clippy::non_send_fields_in_send_ty,
-    reason = "this is expected because of the nature of the struct"
-)]
-unsafe impl Send for SendableOutputStream {}
-
 /// Initializes the audio server, and then safely stops
 /// it when the frontend quits.
-pub async fn play(args: Args) -> eyre::Result<()> {
+pub async fn play(args: Args) -> eyre::Result<(), player::Error> {
+    // TODO: This isn't a great way of doing things,
+    // but it's better than vanilla behaviour at least.
+    let eyre_hook = panic::take_hook();
+
+    panic::set_hook(Box::new(move |x| {
+        let mut lock = stdout().lock();
+        crossterm::execute!(
+            lock,
+            Clear(ClearType::FromCursorDown),
+            Show,
+            PopKeyboardEnhancementFlags
+        )
+        .unwrap();
+        terminal::disable_raw_mode().unwrap();
+
+        eyre_hook(x);
+        exit(1)
+    }));
+
     // Actually initializes the player.
     // Stream kept here in the master thread to keep it alive.
     let (player, stream) = Player::new(&args).await?;
@@ -102,19 +44,35 @@ pub async fn play(args: Args) -> eyre::Result<()> {
 
     // Initialize the UI, as well as the internal communication channel.
     let (tx, rx) = mpsc::channel(8);
-    let ui = task::spawn(ui::start(Arc::clone(&player), tx.clone(), args));
+    let ui = if stdout().is_terminal() && !(env::var("LOWFI_DISABLE_UI") == Ok("1".to_owned())) {
+        Some(task::spawn(ui::start(
+            Arc::clone(&player),
+            tx.clone(),
+            args.clone(),
+        )))
+    } else {
+        None
+    };
 
     // Sends the player an "init" signal telling it to start playing a song straight away.
-    tx.send(Messages::Init).await?;
+    tx.send(Message::Init).await?;
 
     // Actually starts the player.
-    Player::play(Arc::clone(&player), tx.clone(), rx).await?;
+    Player::play(Arc::clone(&player), tx.clone(), rx, args.debug).await?;
 
     // Save the volume.txt file for the next session.
-    PersistentVolume::save(player.sink.volume()).await?;
+    PersistentVolume::save(player.sink.volume())
-    drop(stream.0);
+        .await
+        .map_err(player::Error::PersistentVolumeSave)?;
+
+    // Save the bookmarks for the next session.
+    player.bookmarks.save().await?;
+
+    drop(stream);
     player.sink.stop();
-    ui.abort();
+    if let Some(x) = ui {
+        x.abort();
+    }
 
     Ok(())
 }

src/player.rs

@@ -5,9 +5,10 @@
 use std::{collections::VecDeque, sync::Arc, time::Duration};
 
 use arc_swap::ArcSwapOption;
+use atomic_float::AtomicF32;
 use downloader::Downloader;
 use reqwest::Client;
-use rodio::{OutputStream, OutputStreamHandle, Sink};
+use rodio::{OutputStream, OutputStreamBuilder, Sink};
 use tokio::{
     select,
     sync::{
@@ -15,65 +16,31 @@ use tokio::{
         RwLock,
     },
     task,
-    time::sleep,
 };
 
 #[cfg(feature = "mpris")]
 use mpris_server::{PlaybackStatus, PlayerInterface, Property};
 
 use crate::{
-    play::{PersistentVolume, SendableOutputStream},
+    messages::Message,
+    player::{self, bookmark::Bookmarks, persistent_volume::PersistentVolume},
     tracks::{self, list::List},
     Args,
 };
 
+pub mod audio;
+pub mod bookmark;
 pub mod downloader;
+pub mod error;
+pub mod persistent_volume;
+pub mod queue;
 pub mod ui;
 
+pub use error::Error;
+
 #[cfg(feature = "mpris")]
 pub mod mpris;
 
-/// Handles communication between the frontend & audio player.
-#[derive(PartialEq, Debug, Clone, Copy)]
-pub enum Messages {
-    /// Notifies the audio server that it should update the track.
-    Next,
-
-    /// Special in that this isn't sent in a "client to server" sort of way,
-    /// but rather is sent by a child of the server when a song has not only
-    /// been requested but also downloaded aswell.
-    NewSong,
-
-    /// This signal is only sent if a track timed out. In that case,
-    /// lowfi will try again and again to retrieve the track.
-    TryAgain,
-
-    /// Similar to Next, but specific to the first track.
-    Init,
-
-    /// Unpause the [Sink].
-    #[allow(dead_code, reason = "this code may not be dead depending on features")]
-    Play,
-
-    /// Pauses the [Sink].
-    Pause,
-
-    /// Pauses the [Sink]. This will also unpause it if it is paused.
-    PlayPause,
-
-    /// Change the volume of playback.
-    ChangeVolume(f32),
-
-    /// Quits gracefully.
-    Quit,
-}
-
-/// The time to wait in between errors.
-const TIMEOUT: Duration = Duration::from_secs(5);
-
-/// The amount of songs to buffer up.
-const BUFFER_SIZE: usize = 5;
-
 /// Main struct responsible for queuing up & playing tracks.
 // TODO: Consider refactoring [Player] from being stored in an [Arc], into containing many smaller [Arc]s.
 // TODO: In other words, this would change the type from `Arc<Player>` to just `Player`.
@@ -85,15 +52,28 @@ pub struct Player {
     /// [rodio]'s [`Sink`] which can control playback.
     pub sink: Sink,
 
+    /// The internal buffer size.
+    pub buffer_size: usize,
+
     /// The [`TrackInfo`] of the current track.
     /// This is [`None`] when lowfi is buffering/loading.
     current: ArcSwapOption<tracks::Info>,
 
+    /// The current progress for downloading tracks, if
+    /// `current` is None.
+    progress: AtomicF32,
+
     /// The tracks, which is a [`VecDeque`] that holds
     /// *undecoded* [Track]s.
     ///
     /// This is populated specifically by the [Downloader].
-    tracks: RwLock<VecDeque<tracks::Track>>,
+    tracks: RwLock<VecDeque<tracks::QueuedTrack>>,
+
+    /// The bookmarks, which are saved on quit.
+    pub bookmarks: Bookmarks,
+
+    /// The timeout for track downloads, as a [Duration].
+    timeout: Duration,
 
     /// The actual list of tracks to be played.
     list: List,
@@ -104,57 +84,9 @@ pub struct Player {
     /// The web client, which can contain a `UserAgent` & some
     /// settings that help lowfi work more effectively.
     client: Client,
-
-    /// The [`OutputStreamHandle`], which also can control some
-    /// playback, is for now unused and is here just to keep it
-    /// alive so the playback can function properly.
-    _handle: OutputStreamHandle,
 }
 
 impl Player {
-    /// This gets the output stream while also shutting up alsa with [libc].
-    /// Uses raw libc calls, and therefore is functional only on Linux.
-    ///
-    /// In other words, for the younger generation, we're telling alsa
-    /// to simply just the audio in the bag, lil api.
-    #[cfg(target_os = "linux")]
-    fn silent_get_output_stream() -> eyre::Result<(OutputStream, OutputStreamHandle)> {
-        use libc::freopen;
-        use std::ffi::CString;
-
-        // Get the file descriptor to stderr from libc.
-        extern "C" {
-            static stderr: *mut libc::FILE;
-        }
-
-        // This is a bit of an ugly hack that basically just uses `libc` to redirect alsa's
-        // output to `/dev/null` so that it wont be shoved down our throats.
-
-        // The mode which to redirect terminal output with.
-        let mode = CString::new("w")?;
-
-        // First redirect to /dev/null, which basically silences alsa.
-        let null = CString::new("/dev/null")?;
-
-        // SAFETY: Simple enough to be impossible to fail. Hopefully.
-        unsafe {
-            freopen(null.as_ptr(), mode.as_ptr(), stderr);
-        }
-
-        // Make the OutputStream while stderr is still redirected to /dev/null.
-        let (stream, handle) = OutputStream::try_default()?;
-
-        // Redirect back to the current terminal, so that other output isn't silenced.
-        let tty = CString::new("/dev/tty")?;
-
-        // SAFETY: See the first call to `freopen`.
-        unsafe {
-            freopen(tty.as_ptr(), mode.as_ptr(), stderr);
-        }
-
-        Ok((stream, handle))
-    }
-
     /// Just a shorthand for setting `current`.
     fn set_current(&self, info: tracks::Info) {
         self.current.store(Some(Arc::new(info)));
@@ -173,26 +105,34 @@ impl Player {
     /// Initializes the entire player, including audio devices & sink.
     ///
     /// This also will load the track list & persistent volume.
-    pub async fn new(args: &Args) -> eyre::Result<(Self, SendableOutputStream)> {
+    pub async fn new(args: &Args) -> eyre::Result<(Self, OutputStream), player::Error> {
+        // Load the bookmarks.
+        let bookmarks = Bookmarks::load().await?;
+
         // Load the volume file.
-        let volume = PersistentVolume::load().await?;
+        let volume = PersistentVolume::load()
+            .await
+            .map_err(player::Error::PersistentVolumeLoad)?;
 
         // Load the track list.
-        let list = List::load(args.tracklist.as_ref()).await?;
+        let list = List::load(args.track_list.as_ref())
+            .await
+            .map_err(player::Error::TrackListLoad)?;
 
         // We should only shut up alsa forcefully on Linux if we really have to.
         #[cfg(target_os = "linux")]
-        let (stream, handle) = if !args.alternate && !args.debug {
+        let mut stream = if !args.alternate && !args.debug {
-            Self::silent_get_output_stream()?
+            audio::silent_get_output_stream()?
         } else {
-            OutputStream::try_default()?
+            OutputStreamBuilder::open_default_stream()?
         };
 
-        // If we're not on Linux, then there's no problem.
         #[cfg(not(target_os = "linux"))]
-        let (stream, handle) = OutputStream::try_default()?;
+        let mut stream = OutputStreamBuilder::open_default_stream()?;
+
+        stream.log_on_drop(false); // Frankly, this is a stupid feature. Stop shoving your crap into my beloved stderr!!!
+        let sink = Sink::connect_new(stream.mixer());
 
-        let sink = Sink::try_new(&handle)?;
         if args.paused {
             sink.pause();
         }
@@ -203,90 +143,23 @@ impl Player {
                 "/",
                 env!("CARGO_PKG_VERSION")
             ))
-            .timeout(TIMEOUT)
+            .timeout(Duration::from_secs(args.timeout * 5))
             .build()?;
 
         let player = Self {
-            tracks: RwLock::new(VecDeque::with_capacity(5)),
+            tracks: RwLock::new(VecDeque::with_capacity(args.buffer_size)),
+            buffer_size: args.buffer_size,
             current: ArcSwapOption::new(None),
+            progress: AtomicF32::new(0.0),
+            timeout: Duration::from_secs(args.timeout),
+            bookmarks,
             client,
             sink,
             volume,
             list,
-            _handle: handle,
         };
 
-        Ok((player, SendableOutputStream(stream)))
+        Ok((player, stream))
-    }
-
-    /// This will play the next track, as well as refilling the buffer in the background.
-    ///
-    /// This will also set `current` to the newly loaded song.
-    pub async fn next(&self) -> eyre::Result<tracks::Decoded> {
-        // TODO: Consider replacing this with `unwrap_or_else` when async closures are stablized.
-        let track = self.tracks.write().await.pop_front();
-        let track = if let Some(track) = track {
-            track
-        } else {
-            // If the queue is completely empty, then fallback to simply getting a new track.
-            // This is relevant particularly at the first song.
-
-            // Serves as an indicator that the queue is "loading".
-            // We're doing it here so that we don't get the "loading" display
-            // for only a frame in the other case that the buffer is not empty.
-            self.current.store(None);
-
-            self.list.random(&self.client).await.0?
-        };
-
-        let decoded = track.decode()?;
-
-        // Set the current track.
-        self.set_current(decoded.info.clone());
-
-        Ok(decoded)
-    }
-
-    /// This basically just calls [`Player::next`], and then appends the new track to the player.
-    ///
-    /// This also notifies the background thread to get to work, and will send `TryAgain`
-    /// if it fails. This functions purpose is to be called in the background, so that
-    /// when the audio server recieves a `Next` signal it will still be able to respond to other
-    /// signals while it's loading.
-    ///
-    /// This also sends the `NewSong` signal to `tx` apon successful completion.
-    async fn handle_next(
-        player: Arc<Self>,
-        itx: Sender<()>,
-        tx: Sender<Messages>,
-    ) -> eyre::Result<()> {
-        // Stop the sink.
-        player.sink.stop();
-
-        let track = player.next().await;
-
-        match track {
-            Ok(track) => {
-                // Start playing the new track.
-                player.sink.append(track.data);
-
-                // Notify the background downloader that there's an empty spot
-                // in the buffer.
-                Downloader::notify(&itx).await?;
-
-                // Notify the audio server that the next song has actually been downloaded.
-                tx.send(Messages::NewSong).await?;
-            }
-            Err(error) => {
-                if !error.downcast::<reqwest::Error>()?.is_timeout() {
-                    sleep(TIMEOUT).await;
-                }
-
-                tx.send(Messages::TryAgain).await?;
-            }
-        };
-
-        Ok(())
     }
 
     /// This is the main "audio server".
@@ -295,11 +168,13 @@ impl Player {
     /// skip tracks or pause.
     ///
     /// This will also initialize a [Downloader] as well as an MPRIS server if enabled.
+    /// The [Downloader]s internal buffer size is determined by `buf_size`.
     pub async fn play(
         player: Arc<Self>,
-        tx: Sender<Messages>,
+        tx: Sender<Message>,
-        mut rx: Receiver<Messages>,
+        mut rx: Receiver<Message>,
-    ) -> eyre::Result<()> {
+        debug: bool,
+    ) -> eyre::Result<(), player::Error> {
         // Initialize the mpris player.
         //
         // We're initializing here, despite MPRIS being a "user interface",
@@ -315,7 +190,7 @@ impl Player {
 
         // `itx` is used to notify the `Downloader` when it needs to download new tracks.
         let downloader = Downloader::new(Arc::clone(&player));
-        let (itx, downloader) = downloader.start();
+        let (itx, downloader) = downloader.start(debug);
 
         // Start buffering tracks immediately.
         Downloader::notify(&itx).await?;
@@ -327,7 +202,7 @@ impl Player {
         // only want to autoplay if there hasn't been any manual intervention.
         //
         // In other words, this will be `true` after a new track has been fully
-        // loaded  and it'll be `false` if a track is still currently loading.
+        // loaded and it'll be `false` if a track is still currently loading.
         let mut new = false;
 
         loop {
@@ -349,41 +224,42 @@ impl Player {
                 // It's also important to note that the condition is only checked at the
                 // beginning of the loop, not throughout.
                 Ok(()) = task::spawn_blocking(move || clone.sink.sleep_until_end()),
-                        if new => Messages::Next,
+                        if new => Message::Next,
             };
 
             match msg {
-                Messages::Next | Messages::Init | Messages::TryAgain => {
+                Message::Next | Message::Init | Message::TryAgain => {
                     // We manually skipped, so we shouldn't actually wait for the song
                     // to be over until we recieve the `NewSong` signal.
                     new = false;
 
                     // This basically just prevents `Next` while a song is still currently loading.
-                    if msg == Messages::Next && !player.current_exists() {
+                    if msg == Message::Next && !player.current_exists() {
                         continue;
                     }
 
                     // Handle the rest of the signal in the background,
                     // as to not block the main audio server thread.
-                    task::spawn(Self::handle_next(
+                    task::spawn(Self::next(
                         Arc::clone(&player),
                         itx.clone(),
                         tx.clone(),
+                        debug,
                     ));
                 }
-                Messages::Play => {
+                Message::Play => {
                     player.sink.play();
 
                     #[cfg(feature = "mpris")]
                     mpris.playback(PlaybackStatus::Playing).await?;
                 }
-                Messages::Pause => {
+                Message::Pause => {
                     player.sink.pause();
 
                     #[cfg(feature = "mpris")]
                     mpris.playback(PlaybackStatus::Paused).await?;
                 }
-                Messages::PlayPause => {
+                Message::PlayPause => {
                     if player.sink.is_paused() {
                         player.sink.play();
                     } else {
@@ -395,7 +271,7 @@ impl Player {
                         .playback(mpris.player().playback_status().await?)
                         .await?;
                 }
-                Messages::ChangeVolume(change) => {
+                Message::ChangeVolume(change) => {
                     player.set_volume(player.sink.volume() + change);
 
                     #[cfg(feature = "mpris")]
@@ -406,7 +282,7 @@ impl Player {
                 // This basically just continues, but more importantly, it'll re-evaluate
                 // the select macro at the beginning of the loop.
                 // See the top section to find out why this matters.
-                Messages::NewSong => {
+                Message::NewSong => {
                     // We've recieved `NewSong`, so on the next loop iteration we'll
                     // begin waiting for the song to be over in order to autoplay.
                     new = true;
@@ -421,7 +297,13 @@ impl Player {
 
                     continue;
                 }
-                Messages::Quit => break,
+                Message::Bookmark => {
+                    let current = player.current.load();
+                    let current = current.as_ref().unwrap();
+
+                    player.bookmarks.bookmark(current).await?;
+                }
+                Message::Quit => break,
             }
         }
 

src/player/audio.rs

@@ -0,0 +1,40 @@
+/// This gets the output stream while also shutting up alsa with [libc].
+/// Uses raw libc calls, and therefore is functional only on Linux.
+#[cfg(target_os = "linux")]
+pub fn silent_get_output_stream() -> eyre::Result<rodio::OutputStream, crate::player::Error> {
+    use libc::freopen;
+    use rodio::OutputStreamBuilder;
+    use std::ffi::CString;
+
+    // Get the file descriptor to stderr from libc.
+    extern "C" {
+        static stderr: *mut libc::FILE;
+    }
+
+    // This is a bit of an ugly hack that basically just uses `libc` to redirect alsa's
+    // output to `/dev/null` so that it wont be shoved down our throats.
+
+    // The mode which to redirect terminal output with.
+    let mode = CString::new("w")?;
+
+    // First redirect to /dev/null, which basically silences alsa.
+    let null = CString::new("/dev/null")?;
+
+    // SAFETY: Simple enough to be impossible to fail. Hopefully.
+    unsafe {
+        freopen(null.as_ptr(), mode.as_ptr(), stderr);
+    }
+
+    // Make the OutputStream while stderr is still redirected to /dev/null.
+    let stream = OutputStreamBuilder::open_default_stream()?;
+
+    // Redirect back to the current terminal, so that other output isn't silenced.
+    let tty = CString::new("/dev/tty")?;
+
+    // SAFETY: See the first call to `freopen`.
+    unsafe {
+        freopen(tty.as_ptr(), mode.as_ptr(), stderr);
+    }
+
+    Ok(stream)
+}

src/player/bookmark.rs

@@ -0,0 +1,107 @@
+//! Module for handling saving, loading, and adding
+//! bookmarks.
+
+use std::path::PathBuf;
+use std::sync::atomic::AtomicBool;
+
+use tokio::sync::RwLock;
+use tokio::{fs, io};
+
+use crate::{data_dir, tracks};
+
+/// Errors that might occur while managing bookmarks.
+#[derive(Debug, thiserror::Error)]
+pub enum BookmarkError {
+    #[error("data directory not found")]
+    DataDir,
+
+    #[error("io failure")]
+    Io(#[from] io::Error),
+}
+
+/// Manages the bookmarks in the current player.
+pub struct Bookmarks {
+    /// The different entries in the bookmarks file.
+    entries: RwLock<Vec<String>>,
+
+    /// The internal bookmarked register, which keeps track
+    /// of whether a track is bookmarked or not.
+    ///
+    /// This is much more efficient than checking every single frame.
+    bookmarked: AtomicBool,
+}
+
+impl Bookmarks {
+    /// Gets the path of the bookmarks file.
+    pub async fn path() -> eyre::Result<PathBuf, BookmarkError> {
+        let data_dir = data_dir().map_err(|_| BookmarkError::DataDir)?;
+        fs::create_dir_all(data_dir.clone()).await?;
+
+        Ok(data_dir.join("bookmarks.txt"))
+    }
+
+    /// Loads bookmarks from the `bookmarks.txt` file.
+    pub async fn load() -> eyre::Result<Self, BookmarkError> {
+        let text = fs::read_to_string(Self::path().await?)
+            .await
+            .unwrap_or_default();
+
+        let lines: Vec<String> = text
+            .trim_start_matches("noheader")
+            .trim()
+            .lines()
+            .filter_map(|x| {
+                if x.is_empty() {
+                    None
+                } else {
+                    Some(x.to_string())
+                }
+            })
+            .collect();
+
+        Ok(Self {
+            entries: RwLock::new(lines),
+            bookmarked: AtomicBool::new(false),
+        })
+    }
+
+    // Saves the bookmarks to the `bookmarks.txt` file.
+    pub async fn save(&self) -> eyre::Result<(), BookmarkError> {
+        let text = format!("noheader\n{}", self.entries.read().await.join("\n"));
+        fs::write(Self::path().await?, text).await?;
+        Ok(())
+    }
+
+    /// Bookmarks a given track with a full path and optional custom name.
+    ///
+    /// Returns whether the track is now bookmarked, or not.
+    pub async fn bookmark(&self, track: &tracks::Info) -> eyre::Result<(), BookmarkError> {
+        let entry = track.to_entry();
+        let idx = self.entries.read().await.iter().position(|x| **x == entry);
+
+        if let Some(idx) = idx {
+            self.entries.write().await.remove(idx);
+        } else {
+            self.entries.write().await.push(entry);
+        };
+
+        self.bookmarked
+            .swap(idx.is_none(), std::sync::atomic::Ordering::Relaxed);
+
+        Ok(())
+    }
+
+    /// Returns whether a track is bookmarked or not by using the internal
+    /// bookmarked register.
+    pub fn bookmarked(&self) -> bool {
+        self.bookmarked.load(std::sync::atomic::Ordering::Relaxed)
+    }
+
+    /// Sets the internal bookmarked register by checking against
+    /// the current track's info.
+    pub async fn set_bookmarked(&self, track: &tracks::Info) {
+        let val = self.entries.read().await.contains(&track.to_entry());
+        self.bookmarked
+            .swap(val, std::sync::atomic::Ordering::Relaxed);
+    }
+}

src/player/downloader.rs

@@ -1,6 +1,6 @@
 //! Contains the [`Downloader`] struct.
 
-use std::sync::Arc;
+use std::{error::Error, sync::Arc};
 
 use tokio::{
     sync::mpsc::{self, Receiver, Sender},
@@ -8,7 +8,7 @@ use tokio::{
     time::sleep,
 };
 
-use super::{Player, BUFFER_SIZE, TIMEOUT};
+use super::Player;
 
 /// This struct is responsible for downloading tracks in the background.
 ///
@@ -42,27 +42,37 @@ impl Downloader {
         Self { player, rx, tx }
     }
 
-    /// Actually starts & consumes the [Downloader].
+    /// Push a new, random track onto the internal buffer.
-    pub fn start(mut self) -> (Sender<()>, JoinHandle<()>) {
+    pub async fn push_buffer(&self, debug: bool) {
-        (
+        let data = self.player.list.random(&self.player.client, None).await;
-            self.tx,
+        match data {
-            task::spawn(async move {
+            Ok(track) => self.player.tracks.write().await.push_back(track),
-                // Loop through each update notification.
+            Err(error) => {
-                while self.rx.recv().await == Some(()) {
+                if debug {
-                    //  For each update notification, we'll push tracks until the buffer is completely full.
+                    panic!("{error} - {:?}", error.source())
-                    while self.player.tracks.read().await.len() < BUFFER_SIZE {
-                        let (data, timeout) = self.player.list.random(&self.player.client).await;
-                        match data {
-                            Ok(track) => self.player.tracks.write().await.push_back(track),
-                            Err(_) => {
-                                if !timeout {
-                                    sleep(TIMEOUT).await;
-                                }
-                            }
-                        }
-                    }
                 }
-            }),
+
-        )
+                if !error.is_timeout() {
+                    sleep(self.player.timeout).await;
+                }
+            }
+        }
+    }
+
+    /// Actually starts & consumes the [Downloader].
+    pub fn start(mut self, debug: bool) -> (Sender<()>, JoinHandle<()>) {
+        let tx = self.tx.clone();
+
+        let handle = task::spawn(async move {
+            // Loop through each update notification.
+            while self.rx.recv().await == Some(()) {
+                //  For each update notification, we'll push tracks until the buffer is completely full.
+                while self.player.tracks.read().await.len() < self.player.buffer_size {
+                    self.push_buffer(debug).await;
+                }
+            }
+        });
+
+        (tx, handle)
     }
 }

src/player/error.rs

@@ -0,0 +1,51 @@
+use std::ffi::NulError;
+
+use crate::{messages::Message, player::bookmark::BookmarkError};
+use tokio::sync::mpsc::error::SendError;
+
+#[cfg(feature = "mpris")]
+use mpris_server::zbus::{self, fdo};
+
+/// Any errors which might occur when running or initializing the lowfi player.
+#[derive(thiserror::Error, Debug)]
+pub enum Error {
+    #[error("unable to load the persistent volume")]
+    PersistentVolumeLoad(eyre::Error),
+
+    #[error("unable to save the persistent volume")]
+    PersistentVolumeSave(eyre::Error),
+
+    #[error("sending internal message failed")]
+    Communication(#[from] SendError<Message>),
+
+    #[error("unable to load track list")]
+    TrackListLoad(eyre::Error),
+
+    #[error("interfacing with audio failed")]
+    Stream(#[from] rodio::StreamError),
+
+    #[error("NUL error, if you see this, something has gone VERY wrong")]
+    Nul(#[from] NulError),
+
+    #[error("unable to send or prepare network request")]
+    Reqwest(#[from] reqwest::Error),
+
+    #[cfg(feature = "mpris")]
+    #[error("mpris bus error")]
+    ZBus(#[from] zbus::Error),
+
+    // TODO: This has a terrible error message, mainly because I barely understand
+    // what this error even represents. What does fdo mean?!?!? Why, MPRIS!?!?
+    #[cfg(feature = "mpris")]
+    #[error("mpris fdo (zbus interface) error")]
+    Fdo(#[from] fdo::Error),
+
+    #[error("unable to notify downloader")]
+    DownloaderNotify(#[from] SendError<()>),
+
+    #[error("unable to find data directory")]
+    DataDir,
+
+    #[error("bookmarking load/unload failed")]
+    Bookmark(#[from] BookmarkError),
+}

src/player/mpris.rs

@@ -1,6 +1,6 @@
 //! Contains the code for the MPRIS server & other helper functions.
 
-use std::{process, sync::Arc};
+use std::{env, process, sync::Arc};
 
 use mpris_server::{
     zbus::{self, fdo, Result},
@@ -10,7 +10,7 @@ use mpris_server::{
 use tokio::sync::mpsc::Sender;
 
 use super::ui;
-use super::Messages;
+use super::Message;
 
 const ERROR: fdo::Error = fdo::Error::Failed(String::new());
 
@@ -21,7 +21,7 @@ pub struct Player {
 
     /// The audio server sender, which is used to communicate with
     /// the audio sender for skips and a few other inputs.
-    pub sender: Sender<Messages>,
+    pub sender: Sender<Message>,
 }
 
 impl RootInterface for Player {
@@ -31,7 +31,7 @@ impl RootInterface for Player {
 
     async fn quit(&self) -> fdo::Result<()> {
         self.sender
-            .send(Messages::Quit)
+            .send(Message::Quit)
             .await
             .map_err(|_error| ERROR)
     }
@@ -80,7 +80,7 @@ impl RootInterface for Player {
 impl PlayerInterface for Player {
     async fn next(&self) -> fdo::Result<()> {
         self.sender
-            .send(Messages::Next)
+            .send(Message::Next)
             .await
             .map_err(|_error| ERROR)
     }
@@ -91,14 +91,14 @@ impl PlayerInterface for Player {
 
     async fn pause(&self) -> fdo::Result<()> {
         self.sender
-            .send(Messages::Pause)
+            .send(Message::Pause)
             .await
             .map_err(|_error| ERROR)
     }
 
     async fn play_pause(&self) -> fdo::Result<()> {
         self.sender
-            .send(Messages::PlayPause)
+            .send(Message::PlayPause)
             .await
             .map_err(|_error| ERROR)
     }
@@ -109,7 +109,7 @@ impl PlayerInterface for Player {
 
     async fn play(&self) -> fdo::Result<()> {
         self.sender
-            .send(Messages::Play)
+            .send(Message::Play)
             .await
             .map_err(|_error| ERROR)
     }
@@ -169,7 +169,7 @@ impl PlayerInterface for Player {
             .as_ref()
             .map_or_else(Metadata::new, |track| {
                 let mut metadata = Metadata::builder()
-                    .title(track.name.clone())
+                    .title(track.display_name.clone())
                     .album(self.player.list.name.clone())
                     .build();
 
@@ -247,10 +247,8 @@ impl Server {
     pub async fn changed(
         &self,
         properties: impl IntoIterator<Item = mpris_server::Property> + Send + Sync,
-    ) -> eyre::Result<()> {
+    ) -> zbus::Result<()> {
-        self.inner.properties_changed(properties).await?;
+        self.inner.properties_changed(properties).await
-
-        Ok(())
     }
 
     /// Shorthand to emit a `PropertiesChanged` signal, specifically about playback.
@@ -266,8 +264,15 @@ impl Server {
     }
 
     /// Creates a new MPRIS server.
-    pub async fn new(player: Arc<super::Player>, sender: Sender<Messages>) -> eyre::Result<Self> {
+    pub async fn new(
-        let suffix = format!("lowfi.{}.instance{}", player.list.name, process::id());
+        player: Arc<super::Player>,
+        sender: Sender<Message>,
+    ) -> eyre::Result<Self, zbus::Error> {
+        let suffix = if env::var("LOWFI_FIXED_MPRIS_NAME").is_ok_and(|x| x == "1") {
+            String::from("lowfi")
+        } else {
+            format!("lowfi.{}.instance{}", player.list.name, process::id())
+        };
 
         let server = mpris_server::Server::new(&suffix, Player { player, sender }).await?;
 

src/player/persistent_volume.rs

@@ -0,0 +1,70 @@
+use eyre::eyre;
+use std::path::PathBuf;
+use tokio::fs;
+
+/// This is the representation of the persistent volume,
+/// which is loaded at startup and saved on shutdown.
+#[derive(Clone, Copy)]
+pub struct PersistentVolume {
+    /// The volume, as a percentage.
+    inner: u16,
+}
+
+impl PersistentVolume {
+    /// Retrieves the config directory.
+    async fn config() -> eyre::Result<PathBuf> {
+        let config = dirs::config_dir()
+            .ok_or_else(|| eyre!("Couldn't find config directory"))?
+            .join(PathBuf::from("lowfi"));
+
+        if !config.exists() {
+            fs::create_dir_all(&config).await?;
+        }
+
+        Ok(config)
+    }
+
+    /// Returns the volume as a float from 0 to 1.
+    pub fn float(self) -> f32 {
+        f32::from(self.inner) / 100.0
+    }
+
+    /// Loads the [`PersistentVolume`] from [`dirs::config_dir()`].
+    pub async fn load() -> eyre::Result<Self> {
+        let config = Self::config().await?;
+        let volume = config.join(PathBuf::from("volume.txt"));
+
+        // Basically just read from the volume file if it exists, otherwise return 100.
+        let volume = if volume.exists() {
+            let contents = fs::read_to_string(volume).await?;
+            let trimmed = contents.trim();
+            let stripped = trimmed.strip_suffix("%").unwrap_or(trimmed);
+            stripped
+                .parse()
+                .map_err(|_error| eyre!("volume.txt file is invalid"))?
+        } else {
+            fs::write(&volume, "100").await?;
+            100u16
+        };
+
+        Ok(Self { inner: volume })
+    }
+
+    /// Saves `volume` to `volume.txt`.
+    pub async fn save(volume: f32) -> eyre::Result<()> {
+        let config = Self::config().await?;
+        let path = config.join(PathBuf::from("volume.txt"));
+
+        // Already rounded & absolute, therefore this should be safe.
+        #[expect(
+            clippy::as_conversions,
+            clippy::cast_sign_loss,
+            clippy::cast_possible_truncation
+        )]
+        let percentage = (volume * 100.0).abs().round() as u16;
+
+        fs::write(path, percentage.to_string()).await?;
+
+        Ok(())
+    }
+}

src/player/queue.rs

@@ -0,0 +1,88 @@
+use std::{
+    error::Error,
+    sync::{atomic::Ordering, Arc},
+};
+use tokio::{sync::mpsc::Sender, time::sleep};
+
+use crate::{
+    messages::Message,
+    player::{downloader::Downloader, Player},
+    tracks,
+};
+
+impl Player {
+    /// Fetches the next track from the queue, or a random track if the queue is empty.
+    /// This will also set the current track to the fetched track's info.
+    async fn fetch(&self) -> Result<tracks::DecodedTrack, tracks::Error> {
+        // TODO: Consider replacing this with `unwrap_or_else` when async closures are stablized.
+        let track = self.tracks.write().await.pop_front();
+        let track = if let Some(track) = track {
+            track
+        } else {
+            // If the queue is completely empty, then fallback to simply getting a new track.
+            // This is relevant particularly at the first song.
+
+            // Serves as an indicator that the queue is "loading".
+            // We're doing it here so that we don't get the "loading" display
+            // for only a frame in the other case that the buffer is not empty.
+            self.current.store(None);
+            self.progress.store(0.0, Ordering::Relaxed);
+            self.list.random(&self.client, Some(&self.progress)).await?
+        };
+
+        let decoded = track.decode()?;
+
+        // Set the current track.
+        self.set_current(decoded.info.clone());
+
+        Ok(decoded)
+    }
+
+    /// Gets, decodes, and plays the next track in the queue while also handling the downloader.
+    ///
+    /// This functions purpose is to be called in the background, so that when the audio server recieves a
+    /// `Next` signal it will still be able to respond to other signals while it's loading.
+    ///
+    /// This also sends the either a `NewSong` or `TryAgain` signal to `tx`.
+    pub async fn next(
+        player: Arc<Self>,
+        itx: Sender<()>,
+        tx: Sender<Message>,
+        debug: bool,
+    ) -> eyre::Result<()> {
+        // Stop the sink.
+        player.sink.stop();
+
+        let track = player.fetch().await;
+
+        match track {
+            Ok(track) => {
+                // Start playing the new track.
+                player.sink.append(track.data);
+
+                // Set whether it's bookmarked.
+                player.bookmarks.set_bookmarked(&track.info).await;
+
+                // Notify the background downloader that there's an empty spot
+                // in the buffer.
+                Downloader::notify(&itx).await?;
+
+                // Notify the audio server that the next song has actually been downloaded.
+                tx.send(Message::NewSong).await?;
+            }
+            Err(error) => {
+                if debug {
+                    panic!("{error} - {:?}", error.source())
+                }
+
+                if !error.is_timeout() {
+                    sleep(player.timeout).await;
+                }
+
+                tx.send(Message::TryAgain).await?;
+            }
+        };
+
+        Ok(())
+    }
+}

src/player/ui.rs

@@ -28,25 +28,34 @@ use crossterm::{
 };
 
 use lazy_static::lazy_static;
+use thiserror::Error;
 use tokio::{sync::mpsc::Sender, task, time::sleep};
+use unicode_segmentation::UnicodeSegmentation;
 
-use super::{Messages, Player};
+use super::Player;
+use crate::messages::Message;
 
 mod components;
 mod input;
 
-/// Self explanitory.
+/// The error type for the UI, which is used to handle errors that occur
-const FPS: usize = 12;
+/// while drawing the UI or handling input.
+#[derive(Debug, Error)]
+pub enum UIError {
+    #[error("unable to convert number")]
+    Conversion(#[from] std::num::TryFromIntError),
+
+    #[error("unable to write output")]
+    Write(#[from] std::io::Error),
+
+    #[error("sending message to backend from ui failed")]
+    Communication(#[from] tokio::sync::mpsc::error::SendError<Message>),
+}
 
 /// How long the audio bar will be visible for when audio is adjusted.
 /// This is in frames.
 const AUDIO_BAR_DURATION: usize = 10;
 
-/// How long to wait in between frames.
-/// This is fairly arbitrary, but an ideal value should be enough to feel
-/// snappy but not require too many resources.
-const FRAME_DELTA: f32 = 1.0 / FPS as f32;
-
 lazy_static! {
     /// The volume timer, which controls how long the volume display should
     /// show up and when it should disappear.
@@ -77,6 +86,9 @@ pub struct Window {
     /// If the option to not include borders is set, these will just be empty [String]s.
     borders: [String; 2],
 
+    /// The width of the window.
+    width: usize,
+
     /// The output, currently just an [`Stdout`].
     out: Stdout,
 }
@@ -98,19 +110,25 @@ impl Window {
         Self {
             borders,
             borderless,
+            width,
             out: stdout(),
         }
     }
 
     /// Actually draws the window, with each element in `content` being on a new line.
-    pub fn draw(&mut self, content: Vec<String>) -> eyre::Result<()> {
+    pub fn draw(&mut self, content: Vec<String>, space: bool) -> eyre::Result<(), UIError> {
         let len: u16 = content.len().try_into()?;
 
         // Note that this will have a trailing newline, which we use later.
         let menu: String = content.into_iter().fold(String::new(), |mut output, x| {
             // Horizontal Padding & Border
             let padding = if self.borderless { " " } else { "│" };
-            write!(output, "{padding} {} {padding}\r\n", x.reset()).unwrap();
+            let space = if space {
+                " ".repeat(self.width.saturating_sub(x.graphemes(true).count()))
+            } else {
+                String::new()
+            };
+            write!(output, "{padding} {}{space} {padding}\r\n", x.reset()).unwrap();
 
             output
         });
@@ -141,15 +159,15 @@ impl Window {
 /// The code for the terminal interface itself.
 ///
 /// * `minimalist` - All this does is hide the bottom control bar.
-/// * `borderless` - Whether to include borders or not.
-/// * `width` - The width of player
 async fn interface(
     player: Arc<Player>,
     minimalist: bool,
     borderless: bool,
+    debug: bool,
+    fps: u8,
     width: usize,
-) -> eyre::Result<()> {
+) -> eyre::Result<(), UIError> {
-    let mut window = Window::new(width, borderless);
+    let mut window = Window::new(width, borderless || debug);
 
     loop {
         // Load `current` once so that it doesn't have to be loaded over and over
@@ -178,15 +196,16 @@ async fn interface(
 
         let controls = components::controls(width);
 
-        let menu = if minimalist {
+        let menu = match (minimalist, debug, player.current.load().as_ref()) {
-            vec![action, middle]
+            (true, _, _) => vec![action, middle],
-        } else {
+            (false, true, Some(x)) => vec![x.full_path.clone(), action, middle, controls],
-            vec![action, middle, controls]
+            _ => vec![action, middle, controls],
         };
 
-        window.draw(menu)?;
+        window.draw(menu, false)?;
 
-        sleep(Duration::from_secs_f32(FRAME_DELTA)).await;
+        let delta = 1.0 / f32::from(fps);
+        sleep(Duration::from_secs_f32(delta)).await;
     }
 }
 
@@ -203,7 +222,7 @@ pub struct Environment {
 impl Environment {
     /// This prepares the terminal, returning an [Environment] helpful
     /// for cleaning up afterwards.
-    pub fn ready(alternate: bool) -> eyre::Result<Self> {
+    pub fn ready(alternate: bool) -> eyre::Result<Self, UIError> {
         let mut lock = stdout().lock();
 
         crossterm::execute!(lock, Hide)?;
@@ -230,7 +249,7 @@ impl Environment {
 
     /// Uses the information collected from initialization to safely close down
     /// the terminal & restore it to it's previous state.
-    pub fn cleanup(&self) -> eyre::Result<()> {
+    pub fn cleanup(&self) -> eyre::Result<(), UIError> {
         let mut lock = stdout().lock();
 
         if self.alternate {
@@ -263,12 +282,19 @@ impl Drop for Environment {
 ///
 /// `alternate` controls whether to use [`EnterAlternateScreen`] in order to hide
 /// previous terminal history.
-pub async fn start(player: Arc<Player>, sender: Sender<Messages>, args: Args) -> eyre::Result<()> {
+pub async fn start(
+    player: Arc<Player>,
+    sender: Sender<Message>,
+    args: Args,
+) -> eyre::Result<(), UIError> {
     let environment = Environment::ready(args.alternate)?;
+
     let interface = task::spawn(interface(
         Arc::clone(&player),
         args.minimalist,
         args.borderless,
+        args.debug,
+        args.fps,
         21 + args.width.min(32) * 2,
     ));
 

src/player/ui/components.rs

@@ -59,29 +59,46 @@ pub fn audio_bar(volume: f32, percentage: &str, width: usize) -> String {
 
 /// This represents the main "action" bars state.
 enum ActionBar {
-    /// When the app is currently displaying "paused".
+    /// When the app is paused.
     Paused(Info),
 
-    /// When the app is currently displaying "playing".
+    /// When the app is playing.
     Playing(Info),
 
-    /// When the app is currently displaying "loading".
+    /// When the app is loading.
-    Loading,
+    Loading(f32),
+
+    /// When the app is muted.
+    Muted,
 }
 
 impl ActionBar {
     /// Formats the action bar to be displayed.
     /// The second value is the character length of the result.
-    fn format(&self) -> (String, usize) {
+    fn format(&self, star: bool) -> (String, usize) {
         let (word, subject) = match self {
-            Self::Playing(x) => ("playing", Some((x.name.clone(), x.width))),
+            Self::Playing(x) => ("playing", Some((x.display_name.clone(), x.width))),
-            Self::Paused(x) => ("paused", Some((x.name.clone(), x.width))),
+            Self::Paused(x) => ("paused", Some((x.display_name.clone(), x.width))),
-            Self::Loading => ("loading", None),
+            Self::Loading(progress) => {
+                let progress = format!("{: <2.0}%", (progress * 100.0).min(99.0));
+
+                ("loading", Some((progress, 3)))
+            }
+            Self::Muted => {
+                let msg = "+ to increase volume";
+
+                ("muted,", Some((String::from(msg), msg.len())))
+            }
         };
 
         subject.map_or_else(
             || (word.to_owned(), word.len()),
-            |(subject, len)| (format!("{} {}", word, subject.bold()), word.len() + 1 + len),
+            |(subject, len)| {
+                (
+                    format!("{} {}{}", word, if star { "*" } else { "" }, subject.bold()),
+                    word.len() + 1 + len + usize::from(star),
+                )
+            },
         )
     }
 }
@@ -90,16 +107,23 @@ impl ActionBar {
 /// This also creates all the needed padding.
 pub fn action(player: &Player, current: Option<&Arc<Info>>, width: usize) -> String {
     let (main, len) = current
-        .map_or(ActionBar::Loading, |info| {
+        .map_or_else(
-            let info = info.deref().clone();
+            || ActionBar::Loading(player.progress.load(std::sync::atomic::Ordering::Acquire)),
+            |info| {
+                let info = info.deref().clone();
 
-            if player.sink.is_paused() {
+                if player.sink.volume() < 0.01 {
-                ActionBar::Paused(info)
+                    return ActionBar::Muted;
-            } else {
+                }
-                ActionBar::Playing(info)
+
-            }
+                if player.sink.is_paused() {
-        })
+                    ActionBar::Paused(info)
-        .format();
+                } else {
+                    ActionBar::Playing(info)
+                }
+            },
+        )
+        .format(player.bookmarks.bookmarked());
 
     if len > width {
         let chopped: String = main.graphemes(true).take(width + 1).collect();

src/player/ui/input.rs

@@ -5,10 +5,13 @@ use crossterm::event::{self, EventStream, KeyCode, KeyEventKind, KeyModifiers};
 use futures::{FutureExt as _, StreamExt as _};
 use tokio::sync::mpsc::Sender;
 
-use crate::player::{ui, Messages};
+use crate::player::{
+    ui::{self, UIError},
+    Message,
+};
 
 /// Starts the listener to recieve input from the terminal for various events.
-pub async fn listen(sender: Sender<Messages>) -> eyre::Result<()> {
+pub async fn listen(sender: Sender<Message>) -> eyre::Result<(), UIError> {
     let mut reader = EventStream::new();
 
     loop {
@@ -22,26 +25,29 @@ pub async fn listen(sender: Sender<Messages>) -> eyre::Result<()> {
 
         let messages = match event.code {
             // Arrow key volume controls.
-            KeyCode::Up => Messages::ChangeVolume(0.1),
+            KeyCode::Up => Message::ChangeVolume(0.1),
-            KeyCode::Right => Messages::ChangeVolume(0.01),
+            KeyCode::Right => Message::ChangeVolume(0.01),
-            KeyCode::Down => Messages::ChangeVolume(-0.1),
+            KeyCode::Down => Message::ChangeVolume(-0.1),
-            KeyCode::Left => Messages::ChangeVolume(-0.01),
+            KeyCode::Left => Message::ChangeVolume(-0.01),
             KeyCode::Char(character) => match character.to_ascii_lowercase() {
                 // Ctrl+C
-                'c' if event.modifiers == KeyModifiers::CONTROL => Messages::Quit,
+                'c' if event.modifiers == KeyModifiers::CONTROL => Message::Quit,
 
                 // Quit
-                'q' => Messages::Quit,
+                'q' => Message::Quit,
 
                 // Skip/Next
-                's' | 'n' | 'l' => Messages::Next,
+                's' | 'n' | 'l' => Message::Next,
 
                 // Pause
-                'p' | ' ' => Messages::PlayPause,
+                'p' | ' ' => Message::PlayPause,
 
                 // Volume up & down
-                '+' | '=' | 'k' => Messages::ChangeVolume(0.1),
+                '+' | '=' | 'k' => Message::ChangeVolume(0.1),
-                '-' | '_' | 'j' => Messages::ChangeVolume(-0.1),
+                '-' | '_' | 'j' => Message::ChangeVolume(-0.1),
+
+                // Bookmark
+                'b' => Message::Bookmark,
 
                 _ => continue,
             },
@@ -49,18 +55,18 @@ pub async fn listen(sender: Sender<Messages>) -> eyre::Result<()> {
             KeyCode::Media(media) => match media {
                 event::MediaKeyCode::Pause
                 | event::MediaKeyCode::Play
-                | event::MediaKeyCode::PlayPause => Messages::PlayPause,
+                | event::MediaKeyCode::PlayPause => Message::PlayPause,
-                event::MediaKeyCode::Stop => Messages::Pause,
+                event::MediaKeyCode::Stop => Message::Pause,
-                event::MediaKeyCode::TrackNext => Messages::Next,
+                event::MediaKeyCode::TrackNext => Message::Next,
-                event::MediaKeyCode::LowerVolume => Messages::ChangeVolume(-0.1),
+                event::MediaKeyCode::LowerVolume => Message::ChangeVolume(-0.1),
-                event::MediaKeyCode::RaiseVolume => Messages::ChangeVolume(0.1),
+                event::MediaKeyCode::RaiseVolume => Message::ChangeVolume(0.1),
-                event::MediaKeyCode::MuteVolume => Messages::ChangeVolume(-1.0),
+                event::MediaKeyCode::MuteVolume => Message::ChangeVolume(-1.0),
                 _ => continue,
             },
             _ => continue,
         };
 
-        if let Messages::ChangeVolume(_) = messages {
+        if let Message::ChangeVolume(_) = messages {
             ui::flash_audio();
         }
 

src/scrapers.rs

@@ -0,0 +1,88 @@
+use std::path::{Path, PathBuf};
+
+use clap::ValueEnum;
+use eyre::bail;
+use reqwest::Client;
+use tokio::{
+    fs::{self, File},
+    io::AsyncWriteExt,
+};
+
+pub mod archive;
+pub mod chillhop;
+pub mod lofigirl;
+
+/// Represents the different sources which can be scraped.
+#[derive(Clone, Copy, PartialEq, Eq, Debug, ValueEnum)]
+pub enum Source {
+    Lofigirl,
+    Archive,
+    Chillhop,
+}
+
+impl Source {
+    /// Gets the cache directory name, for example, `chillhop`.
+    pub fn cache_dir(&self) -> &'static str {
+        match self {
+            Source::Lofigirl => "lofigirl",
+            Source::Archive => "archive",
+            Source::Chillhop => "chillhop",
+        }
+    }
+
+    /// Gets the full root URL of the source.
+    pub fn url(&self) -> &'static str {
+        match self {
+            Source::Chillhop => "https://chillhop.com",
+            Source::Archive => "https://ia601004.us.archive.org/31/items/lofigirl",
+            Source::Lofigirl => "https://lofigirl.com/wp-content/uploads",
+        }
+    }
+}
+
+/// Sends a get request, with caching.
+async fn get(client: &Client, path: &str, source: Source) -> eyre::Result<String> {
+    let trimmed = path.trim_matches('/');
+    let cache = PathBuf::from(format!("./cache/{}/{trimmed}.html", source.cache_dir()));
+
+    if let Ok(x) = fs::read_to_string(&cache).await {
+        Ok(x)
+    } else {
+        let resp = client
+            .get(format!("{}/{trimmed}", source.url()))
+            .send()
+            .await?;
+
+        let status = resp.status();
+
+        if status == 429 {
+            bail!("rate limit reached: {path}");
+        }
+
+        if status != 404 && !status.is_success() && !status.is_redirection() {
+            bail!("non success code {}: {path}", resp.status().as_u16());
+        }
+
+        let text = resp.text().await?;
+
+        let parent = cache.parent();
+        if let Some(x) = parent {
+            if x != Path::new("") {
+                fs::create_dir_all(x).await?;
+            }
+        }
+
+        let mut file = File::create(&cache).await?;
+        file.write_all(text.as_bytes()).await?;
+
+        if status.is_redirection() {
+            bail!("redirect: {path}")
+        }
+
+        if status == 404 {
+            bail!("not found: {path}")
+        }
+
+        Ok(text)
+    }
+}

src/scrapers/archive.rs

@@ -0,0 +1,74 @@
+//! Has all of the functions for the `scrape` command.
+//!
+//! This command is completely optional, and as such isn't subject to the same
+//! quality standards as the rest of the codebase.
+
+use futures::{stream::FuturesOrdered, StreamExt};
+use lazy_static::lazy_static;
+use reqwest::Client;
+use scraper::{Html, Selector};
+
+use crate::scrapers::{get, Source};
+
+lazy_static! {
+    static ref SELECTOR: Selector = Selector::parse("html > body > pre > a").unwrap();
+}
+
+async fn parse(client: &Client, path: &str) -> eyre::Result<Vec<String>> {
+    let document = get(client, path, super::Source::Lofigirl).await?;
+    let html = Html::parse_document(&document);
+
+    Ok(html
+        .select(&SELECTOR)
+        .skip(1)
+        .map(|x| String::from(x.attr("href").unwrap()))
+        .collect())
+}
+
+/// This function basically just scans the entire file server, and returns a list of paths to mp3 files.
+///
+/// It's a bit hacky, and basically works by checking all of the years, then months, and then all of the files.
+/// This is done as a way to avoid recursion, since async rust really hates recursive functions.
+async fn scan() -> eyre::Result<Vec<String>> {
+    let client = Client::new();
+
+    let mut releases = parse(&client, "/").await?;
+    releases.truncate(releases.len() - 4);
+
+    // A little bit of async to run all of the months concurrently.
+    let mut futures = FuturesOrdered::new();
+
+    for release in releases {
+        let client = client.clone();
+        futures.push_back(async move {
+            let items = parse(&client, &release).await.unwrap();
+            items
+                .into_iter()
+                .filter_map(|x| {
+                    if x.ends_with(".mp3") {
+                        Some(format!("{release}{x}"))
+                    } else {
+                        None
+                    }
+                })
+                .collect::<Vec<String>>()
+        });
+    }
+
+    let mut files = Vec::new();
+    while let Some(mut result) = futures.next().await {
+        files.append(&mut result);
+    }
+
+    eyre::Result::Ok(files)
+}
+
+pub async fn scrape() -> eyre::Result<()> {
+    println!("{}/", Source::Lofigirl.url());
+    let files = scan().await?;
+    for file in files {
+        println!("{file}");
+    }
+
+    Ok(())
+}

src/scrapers/chillhop.rs

@@ -0,0 +1,223 @@
+use eyre::eyre;
+use futures::stream::FuturesUnordered;
+use futures::StreamExt;
+use indicatif::ProgressBar;
+use lazy_static::lazy_static;
+use std::fmt;
+use std::str::FromStr;
+
+use reqwest::Client;
+use scraper::{Html, Selector};
+use serde::{
+    de::{self, Visitor},
+    Deserialize, Deserializer,
+};
+use tokio::fs;
+
+use crate::scrapers::{get, Source};
+
+lazy_static! {
+    static ref RELEASES: Selector = Selector::parse(".table-body > a").unwrap();
+    static ref RELEASE_LABEL: Selector = Selector::parse("label").unwrap();
+    // static ref RELEASE_DATE: Selector = Selector::parse(".release-feat-props > .text-xs").unwrap();
+    // static ref RELEASE_NAME: Selector = Selector::parse(".release-feat-props > h2").unwrap();
+    static ref RELEASE_AUTHOR: Selector = Selector::parse(".release-feat-props .artist-link").unwrap();
+    static ref RELEASE_TEXTAREA: Selector = Selector::parse("textarea").unwrap();
+}
+
+#[derive(Deserialize, Debug)]
+#[serde(rename_all = "camelCase")]
+pub struct Track {
+    title: String,
+    #[serde(deserialize_with = "deserialize_u32_from_string")]
+    file_id: u32,
+    artists: String,
+}
+
+impl Track {
+    pub fn clean(&mut self) {
+        self.artists = html_escape::decode_html_entities(&self.artists).to_string();
+
+        self.title = html_escape::decode_html_entities(&self.title).to_string();
+    }
+}
+
+#[derive(Deserialize, Debug)]
+struct Release {
+    #[serde(skip)]
+    pub path: String,
+
+    #[serde(skip)]
+    pub index: usize,
+
+    pub tracks: Vec<Track>,
+}
+
+#[derive(thiserror::Error, Debug)]
+enum ReleaseError {
+    #[error("invalid release: {0}")]
+    Invalid(#[from] eyre::Error),
+}
+
+impl Release {
+    pub async fn scan(
+        path: String,
+        index: usize,
+        client: Client,
+        bar: ProgressBar,
+    ) -> Result<Self, ReleaseError> {
+        let content = get(&client, &path, Source::Chillhop).await?;
+        let html = Html::parse_document(&content);
+
+        let textarea = html
+            .select(&RELEASE_TEXTAREA)
+            .next()
+            .ok_or(eyre!("unable to find textarea: {path}"))?;
+
+        let mut release: Self = serde_json::from_str(&textarea.inner_html()).unwrap();
+        release.path = path;
+        release.index = index;
+        release.tracks.reverse();
+
+        bar.inc(release.tracks.len() as u64);
+
+        Ok(release)
+    }
+}
+
+async fn scan_page(
+    number: usize,
+    client: &Client,
+    bar: ProgressBar,
+) -> eyre::Result<Vec<impl futures::Future<Output = Result<Release, ReleaseError>>>> {
+    let path = format!("releases/?page={number}");
+    let content = get(client, &path, Source::Chillhop).await?;
+    let html = Html::parse_document(&content);
+
+    let elements = html.select(&RELEASES);
+    Ok(elements
+        .enumerate()
+        .filter_map(|(i, x)| {
+            let label = x.select(&RELEASE_LABEL).next()?.inner_html();
+            if label == "Compilation" {
+                return None;
+            }
+
+            Some(Release::scan(
+                x.attr("href")?.to_string(),
+                (number * 12) + i,
+                client.clone(),
+                bar.clone(),
+            ))
+        })
+        .collect())
+}
+
+pub async fn scrape() -> eyre::Result<()> {
+    const PAGE_COUNT: usize = 40;
+    const USER_AGENT: &str = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/138.0.0.0 Safari/537.36";
+    const TRACK_COUNT: u64 = 1625;
+
+    const IGNORED_TRACKS: [u32; 20] = [
+        // 404
+        74707, // Lyrics
+        21655, 21773, 8172, 55397, 75135, 24827, 8141, 8157, 64052, 31612, 41956, 8001, 9217,
+        55372, // Abnormal
+        8469, 7832, 10448, 9446, 9396,
+    ];
+
+    const IGNORED_ARTISTS: [&str; 1] = [
+        "Kenji", // Lyrics
+    ];
+
+    fs::create_dir_all("./cache/chillhop").await.unwrap();
+    let client = Client::builder().user_agent(USER_AGENT).build().unwrap();
+
+    let futures = FuturesUnordered::new();
+    let bar = ProgressBar::new(TRACK_COUNT + (12 * (PAGE_COUNT as u64)));
+
+    let mut errors = Vec::new();
+
+    // This is slightly less memory efficient than I'd hope, but it is what it is.
+    for page in 0..=PAGE_COUNT {
+        bar.inc(12);
+        for x in scan_page(page, &client, bar.clone()).await? {
+            futures.push(x);
+        }
+    }
+
+    let mut results: Vec<Result<Release, ReleaseError>> = futures.collect().await;
+    bar.finish_and_clear();
+
+    // I mean, is it... optimal? Absolutely not. Does it work? Yes.
+    eprintln!("sorting...");
+    results.sort_by_key(|x| if let Ok(x) = x { x.index } else { 0 });
+    results.reverse();
+
+    eprintln!("printing...");
+    let mut printed = Vec::with_capacity(TRACK_COUNT as usize); // Lazy way to get rid of dupes.
+    for result in results {
+        let release = match result {
+            Ok(release) => release,
+            Err(error) => {
+                errors.push(error);
+                continue;
+            }
+        };
+
+        for mut track in release.tracks {
+            if IGNORED_TRACKS.contains(&track.file_id) {
+                continue;
+            }
+
+            if IGNORED_ARTISTS.contains(&track.artists.as_ref()) {
+                continue;
+            }
+
+            if printed.contains(&track.file_id) {
+                continue;
+            }
+
+            printed.push(track.file_id);
+
+            track.clean();
+            println!("{}!{}", track.file_id, track.title);
+        }
+    }
+
+    eprintln!("-- ERROR REPORT --");
+    for error in errors {
+        eprintln!("{error}");
+    }
+
+    Ok(())
+}
+
+pub fn deserialize_u32_from_string<'de, D>(deserializer: D) -> Result<u32, D::Error>
+where
+    D: Deserializer<'de>,
+{
+    struct U32FromStringVisitor;
+
+    impl<'de> Visitor<'de> for U32FromStringVisitor {
+        type Value = u32;
+
+        fn expecting(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
+            formatter.write_str("a string containing an unsigned 32-bit integer")
+        }
+
+        fn visit_str<E>(self, value: &str) -> Result<Self::Value, E>
+        where
+            E: de::Error,
+        {
+            u32::from_str(value).map_err(|_| {
+                de::Error::invalid_value(
+                    de::Unexpected::Str(value),
+                    &"a valid unsigned 32-bit integer",
+                )
+            })
+        }
+    }
+
+    deserializer.deserialize_str(U32FromStringVisitor)
+}

src/scrapers/lofigirl.rs

@@ -5,19 +5,19 @@
 
 use futures::{stream::FuturesOrdered, StreamExt};
 use lazy_static::lazy_static;
+use reqwest::Client;
 use scraper::{Html, Selector};
 
-const BASE_URL: &str = "https://lofigirl.com/wp-content/uploads/";
+use crate::scrapers::get;
 
 lazy_static! {
     static ref SELECTOR: Selector = Selector::parse("html > body > pre > a").unwrap();
 }
 
-async fn parse(path: &str) -> eyre::Result<Vec<String>> {
+async fn parse(client: &Client, path: &str) -> eyre::Result<Vec<String>> {
-    let response = reqwest::get(format!("{}{}", BASE_URL, path)).await?;
+    let document = get(client, path, super::Source::Lofigirl).await?;
-    let document = response.text().await?;
-
     let html = Html::parse_document(&document);
+
     Ok(html
         .select(&SELECTOR)
         .skip(5)
@@ -29,10 +29,9 @@ async fn parse(path: &str) -> eyre::Result<Vec<String>> {
 ///
 /// It's a bit hacky, and basically works by checking all of the years, then months, and then all of the files.
 /// This is done as a way to avoid recursion, since async rust really hates recursive functions.
-async fn scan(extension: &str, include_full: bool) -> eyre::Result<Vec<String>> {
+async fn scan() -> eyre::Result<Vec<String>> {
-    let extension = &format!(".{}", extension);
+    let client = Client::new();
-
+    let items = parse(&client, "/").await?;
-    let items = parse("").await?;
 
     let mut years: Vec<u32> = items
         .iter()
@@ -48,22 +47,19 @@ async fn scan(extension: &str, include_full: bool) -> eyre::Result<Vec<String>>
     let mut futures = FuturesOrdered::new();
 
     for year in years {
-        let months = parse(&year.to_string()).await?;
+        let months = parse(&client, &year.to_string()).await?;
 
         for month in months {
+            let client = client.clone();
             futures.push_back(async move {
                 let path = format!("{}/{}", year, month);
 
-                let items = parse(&path).await.unwrap();
+                let items = parse(&client, &path).await.unwrap();
                 items
                     .into_iter()
                     .filter_map(|x| {
-                        if x.ends_with(extension) {
+                        if x.ends_with(".mp3") {
-                            if include_full {
+                            Some(format!("{path}{x}"))
-                                Some(format!("{BASE_URL}{path}{x}"))
-                            } else {
-                                Some(format!("{path}{x}"))
-                            }
                         } else {
                             None
                         }
@@ -81,8 +77,8 @@ async fn scan(extension: &str, include_full: bool) -> eyre::Result<Vec<String>>
     eyre::Result::Ok(files)
 }
 
-pub async fn scrape(extension: String, include_full: bool) -> eyre::Result<()> {
+pub async fn scrape() -> eyre::Result<()> {
-    let files = scan(&extension, include_full).await?;
+    let files = scan().await?;
     for file in files {
         println!("{file}");
     }

src/tracks.rs

@@ -1,137 +1,43 @@
 //! Has all of the structs for managing the state
-//! of tracks, as well as downloading them &
+//! of tracks, as well as downloading them & finding new ones.
-//! finding new ones.
+//!
+//! There are several structs which represent the different stages
+//! that go on in downloading and playing tracks. The proccess for fetching tracks,
+//! and what structs are relevant in each step, are as follows.
+//!
+//! First Stage, when a track is initially fetched.
+//! 1. Raw entry selected from track list.
+//! 2. Raw entry split into path & display name.
+//! 3. Track data fetched, and [`QueuedTrack`] is created which includes a [`TrackName`] that may be raw.
+//!
+//! Second Stage, when a track is played.
+//! 1. Track data is decoded.
+//! 2. [`Info`] created from decoded data.
+//! 3. [`Decoded`] made from [`Info`] and the original decoded data.
 
-use std::{io::Cursor, time::Duration};
+use std::{io::Cursor, path::Path, time::Duration};
 
 use bytes::Bytes;
-use eyre::OptionExt as _;
+use convert_case::{Case, Casing};
-use inflector::Inflector as _;
+use regex::Regex;
 use rodio::{Decoder, Source as _};
 use unicode_segmentation::UnicodeSegmentation;
 use url::form_urlencoded;
 
+pub mod error;
 pub mod list;
 
+pub use error::Error;
+
+use crate::tracks::error::Context;
+use lazy_static::lazy_static;
+
 /// Just a shorthand for a decoded [Bytes].
 pub type DecodedData = Decoder<Cursor<Bytes>>;
 
-/// The [`Info`] struct, which has the name and duration of a track.
-///
-/// This is not included in [Track] as the duration has to be acquired
-/// from the decoded data and not from the raw data.
-#[derive(Debug, Eq, PartialEq, Clone)]
-pub struct Info {
-    /// This is a formatted name, so it doesn't include the full path.
-    pub name: String,
-
-    /// This is the *actual* terminal width of the track name, used to make
-    /// the UI consistent.
-    pub width: usize,
-
-    /// The duration of the track, this is an [Option] because there are
-    /// cases where the duration of a track is unknown.
-    pub duration: Option<Duration>,
-}
-
-impl Info {
-    /// Decodes a URL string into normal UTF-8.
-    fn decode_url(text: &str) -> String {
-        #[expect(
-            clippy::tuple_array_conversions,
-            reason = "the tuple contains smart pointers, so it's not really practical to use `into()`"
-        )]
-        form_urlencoded::parse(text.as_bytes())
-            .map(|(key, val)| [key, val].concat())
-            .collect()
-    }
-
-    /// Formats a name with [Inflector].
-    /// This will also strip the first few numbers that are
-    /// usually present on most lofi tracks.
-    fn format_name(name: &str) -> eyre::Result<String> {
-        let split = name
-            .split('/')
-            .last()
-            .ok_or_eyre("split is never supposed to return nothing")?;
-
-        let stripped = split.strip_suffix(".mp3").unwrap_or(split);
-        let formatted = Self::decode_url(stripped)
-            .to_lowercase()
-            .to_title_case()
-            // Inflector doesn't like contractions...
-            // Replaces a few very common ones.
-            // TODO: Properly handle these.
-            .replace(" S ", "'s ")
-            .replace(" T ", "'t ")
-            .replace(" D ", "'d ")
-            .replace(" Ve ", "'ve ")
-            .replace(" Ll ", "'ll ")
-            .replace(" Re ", "'re ")
-            .replace(" M ", "'m ");
-
-        // This is incremented for each digit in front of the song name.
-        let mut skip = 0;
-
-        for character in formatted.as_bytes() {
-            if character.is_ascii_digit() {
-                skip += 1;
-            } else {
-                break;
-            }
-        }
-
-        // If the entire name of the track is a number, then just return it.
-        if skip == formatted.len() {
-            Ok(formatted)
-        } else {
-            #[expect(
-                clippy::string_slice,
-                reason = "We've already checked before that the bound is at an ASCII digit."
-            )]
-            Ok(String::from(&formatted[skip..]))
-        }
-    }
-
-    /// Creates a new [`TrackInfo`] from a possibly raw name & decoded track data.
-    pub fn new(name: TrackName, decoded: &DecodedData) -> eyre::Result<Self> {
-        let name = match name {
-            TrackName::Raw(raw) => Self::format_name(&raw)?,
-            TrackName::Formatted(formatted) => formatted,
-        };
-
-        Ok(Self {
-            duration: decoded.total_duration(),
-            width: name.graphemes(true).count(),
-            name,
-        })
-    }
-}
-
-/// This struct is seperate from [Track] since it is generated lazily from
-/// a track, and not when the track is first downloaded.
-pub struct Decoded {
-    /// Has both the formatted name and some information from the decoded data.
-    pub info: Info,
-
-    /// The decoded data, which is able to be played by [rodio].
-    pub data: DecodedData,
-}
-
-impl Decoded {
-    /// Creates a new track.
-    /// This is equivalent to [`Track::decode`].
-    pub fn new(track: Track) -> eyre::Result<Self> {
-        let data = Decoder::new(Cursor::new(track.data))?;
-        let info = Info::new(track.name, &data)?;
-
-        Ok(Self { info, data })
-    }
-}
-
 /// Specifies a track's name, and specifically,
 /// whether it has already been formatted or if it
-/// is still in it's raw form.
+/// is still in it's raw path form.
 #[derive(Debug, Clone)]
 pub enum TrackName {
     /// Pulled straight from the list,
@@ -143,21 +49,195 @@ pub enum TrackName {
     Formatted(String),
 }
 
-/// The main track struct, which only includes data & the track name.
+/// Tracks which are still waiting in the queue, and can't be played yet.
-pub struct Track {
+///
-    /// Name of the track.
+/// This means that only the data & track name are included.
+pub struct QueuedTrack {
+    /// Name of the track, which may be raw.
     pub name: TrackName,
 
+    /// Full downloadable path/url of the track.
+    pub full_path: String,
+
     /// The raw data of the track, which is not decoded and
     /// therefore much more memory efficient.
     pub data: Bytes,
 }
 
-impl Track {
+impl QueuedTrack {
     /// This will actually decode and format the track,
     /// returning a [`DecodedTrack`] which can be played
     /// and also has a duration & formatted name.
-    pub fn decode(self) -> eyre::Result<Decoded> {
+    pub fn decode(self) -> eyre::Result<DecodedTrack, Error> {
-        Decoded::new(self)
+        DecodedTrack::new(self)
+    }
+}
+
+/// The [`Info`] struct, which has the name and duration of a track.
+///
+/// This is not included in [Track] as the duration has to be acquired
+/// from the decoded data and not from the raw data.
+#[derive(Debug, Eq, PartialEq, Clone)]
+pub struct Info {
+    /// The full downloadable path/url of the track.
+    pub full_path: String,
+
+    /// Whether the track entry included a custom name, or not.
+    pub custom_name: bool,
+
+    /// This is a formatted name, so it doesn't include the full path.
+    pub display_name: String,
+
+    /// This is the *actual* terminal width of the track name, used to make
+    /// the UI consistent.
+    pub width: usize,
+
+    /// The duration of the track, this is an [Option] because there are
+    /// cases where the duration of a track is unknown.
+    pub duration: Option<Duration>,
+}
+
+lazy_static! {
+    static ref MASTER_PATTERNS: [Regex; 5] = [
+        // (master), (master v2)
+        Regex::new(r"\s*\(.*?master(?:\s*v?\d+)?\)$").unwrap(),
+        // mstr or - mstr or (mstr) — now also matches "mstr v3", "mstr2", etc.
+        Regex::new(r"\s*[-(]?\s*mstr(?:\s*v?\d+)?\s*\)?$").unwrap(),
+        // - master, master at end without parentheses
+        Regex::new(r"\s*[-]?\s*master(?:\s*v?\d+)?$").unwrap(),
+        // kupla master1, kupla master v2 (without parentheses or separator)
+        Regex::new(r"\s+kupla\s+master(?:\s*v?\d+|\d+)?$").unwrap(),
+        // (kupla master) followed by trailing parenthetical numbers, e.g. "... (kupla master) (1)"
+        Regex::new(r"\s*\(.*?master(?:\s*v?\d+)?\)(?:\s*\(\d+\))+$").unwrap(),
+    ];
+    static ref ID_PATTERN: Regex = Regex::new(r"^[a-z]\d[ .]").unwrap();
+}
+
+impl Info {
+    /// Converts the info back into a full track list entry.
+    pub fn to_entry(&self) -> String {
+        let mut entry = self.full_path.clone();
+
+        if self.custom_name {
+            entry.push('!');
+            entry.push_str(&self.display_name);
+        }
+
+        entry
+    }
+
+    /// Decodes a URL string into normal UTF-8.
+    fn decode_url(text: &str) -> String {
+        // The tuple contains smart pointers, so it's not really practical to use `into()`.
+        #[allow(clippy::tuple_array_conversions)]
+        form_urlencoded::parse(text.as_bytes())
+            .map(|(key, val)| [key, val].concat())
+            .collect()
+    }
+
+    /// Formats a name with [`convert_case`].
+    ///
+    /// This will also strip the first few numbers that are
+    /// usually present on most lofi tracks and do some other
+    /// formatting operations.
+    fn format_name(name: &str) -> eyre::Result<String, Error> {
+        let path = Path::new(name);
+
+        let name = path
+            .file_stem()
+            .and_then(|x| x.to_str())
+            .ok_or((name, error::Kind::InvalidName))?;
+
+        let name = Self::decode_url(name).to_lowercase();
+        let mut name = name
+            .replace("masster", "master")
+            .replace("(online-audio-converter.com)", "") // Some of these names, man...
+            .replace('_', " ");
+
+        // Get rid of "master" suffix with a few regex patterns.
+        for regex in MASTER_PATTERNS.iter() {
+            name = regex.replace(&name, "").to_string();
+        }
+
+        name = ID_PATTERN.replace(&name, "").to_string();
+
+        let name = name
+            .replace("13lufs", "")
+            .to_case(Case::Title)
+            .replace(" .", "")
+            .replace(" Ft ", " ft. ")
+            .replace("Ft.", "ft.")
+            .replace("Feat.", "ft.")
+            .replace(" W ", " w/ ");
+
+        // This is incremented for each digit in front of the song name.
+        let mut skip = 0;
+
+        for character in name.as_bytes() {
+            if character.is_ascii_digit()
+                || *character == b'.'
+                || *character == b')'
+                || *character == b'('
+            {
+                skip += 1;
+            } else {
+                break;
+            }
+        }
+
+        // If the entire name of the track is a number, then just return it.
+        if skip == name.len() {
+            Ok(name.trim().to_string())
+        } else {
+            // We've already checked before that the bound is at an ASCII digit.
+            #[allow(clippy::string_slice)]
+            Ok(String::from(name[skip..].trim()))
+        }
+    }
+
+    /// Creates a new [`TrackInfo`] from a possibly raw name & decoded data.
+    pub fn new(
+        name: TrackName,
+        full_path: String,
+        decoded: &DecodedData,
+    ) -> eyre::Result<Self, Error> {
+        let (display_name, custom_name) = match name {
+            TrackName::Raw(raw) => (Self::format_name(&raw)?, false),
+            TrackName::Formatted(custom) => (custom, true),
+        };
+
+        Ok(Self {
+            duration: decoded.total_duration(),
+            width: display_name.graphemes(true).count(),
+            full_path,
+            custom_name,
+            display_name,
+        })
+    }
+}
+
+/// This struct is seperate from [Track] since it is generated lazily from
+/// a track, and not when the track is first downloaded.
+pub struct DecodedTrack {
+    /// Has both the formatted name and some information from the decoded data.
+    pub info: Info,
+
+    /// The decoded data, which is able to be played by [rodio].
+    pub data: DecodedData,
+}
+
+impl DecodedTrack {
+    /// Creates a new track.
+    /// This is equivalent to [`QueuedTrack::decode`].
+    pub fn new(track: QueuedTrack) -> eyre::Result<Self, Error> {
+        let data = Decoder::builder()
+            .with_byte_len(track.data.len().try_into().unwrap())
+            .with_data(Cursor::new(track.data))
+            .build()
+            .track(track.full_path.clone())?;
+
+        let info = Info::new(track.name, track.full_path, &data)?;
+
+        Ok(Self { info, data })
     }
 }

src/tracks/error.rs

@@ -0,0 +1,73 @@
+#[derive(Debug, thiserror::Error)]
+pub enum Kind {
+    #[error("unable to decode: {0}")]
+    Decode(#[from] rodio::decoder::DecoderError),
+
+    #[error("invalid name")]
+    InvalidName,
+
+    #[error("invalid file path")]
+    InvalidPath,
+
+    #[error("unknown target track length")]
+    UnknownLength,
+
+    #[error("unable to read file: {0}")]
+    File(#[from] std::io::Error),
+
+    #[error("unable to fetch data: {0}")]
+    Request(#[from] reqwest::Error),
+}
+
+#[derive(Debug, thiserror::Error)]
+#[error("{kind} (track: {track})")]
+pub struct Error {
+    pub track: String,
+
+    #[source]
+    pub kind: Kind,
+}
+
+impl Error {
+    pub fn is_timeout(&self) -> bool {
+        if let Kind::Request(x) = &self.kind {
+            x.is_timeout()
+        } else {
+            false
+        }
+    }
+}
+
+impl<T, E> From<(T, E)> for Error
+where
+    T: Into<String>,
+    Kind: From<E>,
+{
+    fn from((track, err): (T, E)) -> Self {
+        Self {
+            track: track.into(),
+            kind: Kind::from(err),
+        }
+    }
+}
+
+pub trait Context<T> {
+    fn track(self, name: impl Into<String>) -> Result<T, Error>;
+}
+
+impl<T, E> Context<T> for Result<T, E>
+where
+    (String, E): Into<Error>,
+    E: Into<Kind>,
+{
+    fn track(self, name: impl Into<String>) -> Result<T, Error> {
+        self.map_err(|e| {
+            let error = match e.into() {
+                Kind::Request(e) => Kind::Request(e.without_url()),
+                e => e,
+            };
+
+            (name.into(), error).into()
+        })
+    }
+}

src/tracks/list.rs

@@ -1,13 +1,21 @@
 //! The module containing all of the logic behind track lists,
-//! as well as obtaining track names & downloading the raw mp3 data.
+//! as well as obtaining track names & downloading the raw audio data
 
-use bytes::Bytes;
+use std::{cmp::min, sync::atomic::Ordering};
+
+use atomic_float::AtomicF32;
+use bytes::{BufMut, Bytes, BytesMut};
 use eyre::OptionExt as _;
-use rand::Rng as _;
+use futures::StreamExt;
 use reqwest::Client;
 use tokio::fs;
 
-use super::Track;
+use crate::{
+    data_dir,
+    tracks::{self, error::Context},
+};
+
+use super::QueuedTrack;
 
 /// Represents a list of tracks that can be played.
 ///
@@ -15,12 +23,16 @@ use super::Track;
 #[derive(Clone)]
 pub struct List {
     /// The "name" of the list, usually derived from a filename.
-    #[allow(dead_code, reason = "this code may not be dead depending on features")]
+    #[allow(dead_code)]
     pub name: String,
 
     /// Just the raw file, but seperated by `/n` (newlines).
-    /// `lines[0]` is the base, with the rest being tracks.
+    /// `lines[0]` is the base/heaeder, with the rest being tracks.
     lines: Vec<String>,
+
+    /// The file path which the list was read from.
+    #[allow(dead_code)]
+    pub path: Option<String>,
 }
 
 impl List {
@@ -39,7 +51,7 @@ impl List {
         // We're also not pre-trimming `self.lines` into `base` & `tracks` due to
         // how rust vectors work, since it is slower to drain only a single element from
         // the start, so it's faster to just keep it in & work around it.
-        let random = rand::thread_rng().gen_range(1..self.lines.len());
+        let random = fastrand::usize(1..self.lines.len());
         let line = self.lines[random].clone();
 
         if let Some((first, second)) = line.split_once('!') {
@@ -50,56 +62,98 @@ impl List {
     }
 
     /// Downloads a raw track, but doesn't decode it.
-    async fn download(&self, track: &str, client: &Client) -> (eyre::Result<Bytes>, bool) {
+    async fn download(
+        &self,
+        track: &str,
+        client: &Client,
+        progress: Option<&AtomicF32>,
+    ) -> Result<(Bytes, String), tracks::Error> {
         // If the track has a protocol, then we should ignore the base for it.
-        let url = if track.contains("://") {
+        let full_path = if track.contains("://") {
             track.to_owned()
         } else {
             format!("{}{}", self.base(), track)
         };
 
-        let (timeout, data) = if let Some(x) = url.strip_prefix("file://") {
+        let data: Bytes = if let Some(x) = full_path.strip_prefix("file://") {
-            let result = tokio::fs::read(x).await.unwrap();
+            let path = if x.starts_with('~') {
-            (false, Ok(result.into()))
+                let home_path =
-        } else {
+                    dirs::home_dir().ok_or((track, tracks::error::Kind::InvalidPath))?;
-            let response = client.get(url).send().await;
+                let home = home_path
+                    .to_str()
+                    .ok_or((track, tracks::error::Kind::InvalidPath))?;
 
-            match response {
+                x.replace('~', home)
-                Ok(x) => (false, x.bytes().await),
+            } else {
-                Err(x) => (x.is_timeout(), Err(x)),
+                x.to_owned()
+            };
+
+            let result = tokio::fs::read(path.clone()).await.track(track)?;
+            result.into()
+        } else {
+            let response = client.get(full_path.clone()).send().await.track(track)?;
+
+            if let Some(progress) = progress {
+                let total = response
+                    .content_length()
+                    .ok_or((track, tracks::error::Kind::UnknownLength))?;
+                let mut stream = response.bytes_stream();
+                let mut bytes = BytesMut::new();
+                let mut downloaded: u64 = 0;
+
+                while let Some(item) = stream.next().await {
+                    let chunk = item.track(track)?;
+                    let new = min(downloaded + (chunk.len() as u64), total);
+                    downloaded = new;
+                    progress.store((new as f32) / (total as f32), Ordering::Relaxed);
+
+                    bytes.put(chunk);
+                }
+
+                bytes.into()
+            } else {
+                response.bytes().await.track(track)?
             }
         };
 
-        (data.map_err(|x| eyre::eyre!(x)), timeout)
+        Ok((data, full_path))
     }
 
     /// Fetches and downloads a random track from the [List].
-    pub async fn random(&self, client: &Client) -> (eyre::Result<Track>, bool) {
+    ///
+    /// The Result's error is a bool, which is true if a timeout error occured,
+    /// and false otherwise. This tells lowfi if it shouldn't wait to try again.
+    pub async fn random(
+        &self,
+        client: &Client,
+        progress: Option<&AtomicF32>,
+    ) -> Result<QueuedTrack, tracks::Error> {
         let (path, custom_name) = self.random_path();
-        let (data, timeout) = self.download(&path, client).await;
+        let (data, full_path) = self.download(&path, client, progress).await?;
 
-        let name = custom_name.map_or(super::TrackName::Raw(path), |formatted| {
+        let name = custom_name.map_or_else(
-            super::TrackName::Formatted(formatted)
+            || super::TrackName::Raw(path.clone()),
-        });
+            super::TrackName::Formatted,
+        );
 
-        let track = match data {
+        Ok(QueuedTrack {
-            Ok(x) => Ok(Track { name, data: x }),
+            name,
-            Err(x) => Err(x),
+            full_path,
-        };
+            data,
-
+        })
-        (track, timeout)
     }
 
     /// Parses text into a [List].
-    pub fn new(name: &str, text: &str) -> Self {
+    pub fn new(name: &str, text: &str, path: Option<&str>) -> Self {
         let lines: Vec<String> = text
-            .trim()
+            .trim_end()
             .lines()
             .map(|x| x.trim_end().to_owned())
             .collect();
 
         Self {
             lines,
+            path: path.map(ToOwned::to_owned),
             name: name.to_owned(),
         }
     }
@@ -108,25 +162,27 @@ impl List {
     pub async fn load(tracks: Option<&String>) -> eyre::Result<Self> {
         if let Some(arg) = tracks {
             // Check if the track is in ~/.local/share/lowfi, in which case we'll load that.
-            let name = dirs::data_dir()
+            let path = data_dir()?.join(format!("{arg}.txt"));
-                .ok_or_eyre("data directory not found, are you *really* running this on wasm?")?
+            let path = if path.exists() { path } else { arg.into() };
-                .join("lowfi")
-                .join(format!("{arg}.txt"));
 
-            let name = if name.exists() { name } else { arg.into() };
+            let raw = fs::read_to_string(path.clone()).await?;
 
-            let raw = fs::read_to_string(name.clone()).await?;
+            // Get rid of special noheader case for tracklists without a header.
+            let raw = raw
+                .strip_prefix("noheader")
+                .map_or(raw.as_ref(), |stripped| stripped);
 
-            let name = name
+            let name = path
                 .file_stem()
                 .and_then(|x| x.to_str())
                 .ok_or_eyre("invalid track path")?;
 
-            Ok(Self::new(name, &raw))
+            Ok(Self::new(name, raw, path.to_str()))
         } else {
             Ok(Self::new(
-                "lofigirl",
+                "chillhop",
-                include_str!("../../data/lofigirl.txt"),
+                include_str!("../../data/chillhop.txt"),
+                None,
             ))
         }
     }