Documentation

How Pulse works

How Pulse is made and released, how a song gets from a search to your speakers, and how the pieces you can see (themes, settings, your library) fit together.

How Pulse is made

Pulse is a native Windows app written in Rust. There's no web browser hidden inside it: every button, list and cover is drawn by the app itself, straight onto your graphics card.

  • Interface: egui, a toolkit that redraws the window from the app's current state, so what you see always matches what's happening. Drawing goes through wgpu and DirectX 12. On PCs without a working graphics driver, it falls back to Windows' built-in software renderer, so Pulse opens anywhere.
  • Audio: rodio plays the sound and Symphonia decodes MP3, AAC/M4A, FLAC, WAV and Ogg. The equalizer, fades and the rest are Pulse's own code, applied to every sample.
  • Networking: ureq with rustls for secure connections, with no system libraries needed.
  • Everything slow happens off to the side. Searches, downloads, decoding and lookups run on background threads, so the window never freezes while something loads.

The result is one pulse.exe with the Visual C++ runtime and the icon built in. It needs no extra DLLs, and the installer is under 10 MB.

From code to download

Every version you download is built the same way, by machines, from the code in the GitHub repository. Nobody builds a release by hand.

  1. ChangeNew work lands on a separate branch first and is tested there.
  2. BuildEvery push starts a Windows build on GitHub Actions: the release pulse.exe and the test suite.
  3. CheckThe build makes sure the app needs no extra DLLs and that its icon is embedded. A failure stops everything.
  4. PackageInno Setup wraps the app into PulseSetup-x.y.z.exe, an installer that needs no administrator password.
  5. ReleaseWhen the main branch has a new version number, a GitHub release is published with the installer attached. The installer is signed with Pulse's release key, and the signature goes into the release notes.
  6. WebsiteThis site lives in the repo's site folder and is published to GitHub Pages on every change. Its download button always fetches the newest installer.

Versions follow major.minor.patch: the last number for fixes and small additions, the middle one for bigger features. The changes in each version are listed on its release page.

Updating

Once a day, Pulse asks GitHub whether there's a newer version and offers to install it. Before running a downloaded installer, Pulse checks two things: that the file matches the checksum GitHub lists for it, and that it carries a valid signature from Pulse's release key, whose public half is built into Pulse. If either check fails, the installer isn't run, and Pulse opens the release page instead. You can turn update checks off in Settings.

How a song plays

When you press play, a few things happen in a couple of seconds:

  1. Song infoThe title, artists, album, length and cover come from Deezer's catalog.
  2. Finding the audioPulse searches YouTube with yt-dlp and scores the results by title, artist and length, so it picks the right recording, not a live version or a cover.
  3. Remembering itThe match is saved, so the next time you play that song Pulse skips the search. The song itself is kept on disk for a while too (up to 1 GB, Settings → Storage), so playing it again starts at once with nothing to download.
  4. StreamingThe first megabyte is fetched in order so music starts fast. The rest arrives in 1 MB pieces, four at a time, which is much quicker on most connections. Skipping ahead only waits for the piece you jumped to.
  5. Decoding and effectsThe audio is decoded, then the equalizer, mono and fades are applied.
  6. Getting ready for the next oneWhile a song plays, the next one is found and opened ahead of time, so songs change without a wait. Opening a playlist, album, Orbit or search also starts loading its first songs, so the one you press plays straight away.

Two decks, like a DJ

The audio engine has two players. Gapless playback queues the next song on the same player, so it starts on the exact sample the last one ends. Crossfade and automix start the next song on the second player and fade between the two. Automix also listens for silence at the end of a song and starts the next one where the music actually stops.

The first song

YouTube playback needs two free tools, yt-dlp and Deno (about 70 MB together). Pulse downloads them the first time you play a song, from their official GitHub releases, and checks each against its published checksum before using it. After that, Pulse checks once a day for a new yt-dlp and updates it in the background, so playback keeps working when YouTube changes.

Pulse only plays full songs. If YouTube can't play one, Pulse tells you and moves on; it never falls back to a 30-second preview.

Where music info comes from

Charts, search results, artist pages, albums, playlists and covers come from the free Deezer API. No account or key is needed.

  • Every credited artist. A song's main artist and its featured artists come from its credits, so a track released under a label or collective still shows the artists who perform on it. Each name opens that artist's page.
  • Most popular songs. Artist pages show the ten most popular songs, ordered by Deezer's popularity score.
  • Whole albums and playlists. Long albums and playlists are fetched page by page until every song is there, so playing one queues all of it, in order.
  • Missing covers are looked up in the iTunes catalog. YouTube view counts come from YouTube's public numbers.
  • Lyrics come from LRCLIB, a free, open lyrics library. Most come with timings, so the side panel follows along with the song.
  • Search suggestions mix what's in your library with Google's public search suggestions, then the artist, albums, songs and playlists that match on Deezer. Popular artists come first.
  • Recommendations ("Listeners of X also listen to", "Songs like X") are built from the artists and songs you play, using Deezer's related artists and similar songs.

Asking politely

Deezer allows about 50 requests every 5 seconds. Pulse keeps recent replies for ten minutes so the same question isn't asked twice, and when Deezer says it's busy, Pulse waits and tries again instead of showing an error. When you rest the pointer on an album or artist card, Pulse loads that page in the background (two at a time at most), so it opens instantly when you click.

Importing playlists

Press the import button next to Playlists in the sidebar and paste a link. Pulse reads the song list from the public page, so you don't sign in anywhere:

  • YouTube and YouTube Music playlists, up to 5,000 songs. Pulse plays the exact videos in the playlist.
  • Spotify playlists and albums. A link brings in the first 100 songs, which is all Spotify's public page shows. For a longer playlist, open it in Spotify, press Ctrl+A then Ctrl+C, and paste: that copies a link to every song.
  • SoundCloud playlists.

Each song is matched to Deezer's catalog for its cover and details, and plays from YouTube like any other.

Sound and effects

  • Equalizer: six bands (60 Hz to 15 kHz), each a peaking filter, with presets and your own saved settings. When bands are boosted, the overall volume is lowered a little so loud songs don't distort.
  • Crossfade: up to 10 seconds of overlap between songs.
  • Gapless: no silence between songs that are meant to run together.
  • Automix: trims silence at the ends of songs and blends into the next.
  • Mono: both speakers get the same sound, for one earbud or a single speaker.

All of these work the same on streamed songs, downloaded songs and the files in your Music folder.

Staying light

A music player runs for hours next to everything else on your PC, so Pulse tries to use as little as it can:

  • No browser engine and no background services. When you close Pulse, it's gone.
  • Network requests are kept to what a page needs, and repeated ones are answered from memory.
  • Work that takes time (searching, streaming, decoding, lookups) never runs on the thread that draws the window.
  • Moving backgrounds and other motion can be turned off in Settings, with Reduce motion or Moving background.
  • It prefers the battery-friendly graphics chip on laptops with two.
  • Long lists only draw the rows you can see, so a playlist with 10,000 songs scrolls like one with 10.
  • Lookups that fill in details (genres, featured artists) run slowly in the background and redraw the window once per batch, not once per answer. If Pulse is offline, it tries them again another time.
  • Covers are kept in a cache on disk (up to 300 MB) and let go of in memory when they're off screen.
  • Gaming Mode (the Gaming button in the top bar, or Ctrl + G) and Ultra-low mode (in Settings) switch off extras like animations, moving backgrounds and background lookups, for when every bit of your PC counts. The music plays the same in every mode.

Making a theme

Pulse comes with five themes: Default, Blossom, Dreary Mono, Lunar and Aurora. Each has a dark and a light version. To make your own, open Settings → Themes and choose Make a copy of one to start from, or create a folder yourself:

%APPDATA%\pulse-player\themes\My Theme\
    color.ini    colors (one section per color scheme)
    user.css     shapes and spacing
    theme.toml   name and layout

Any of the three files can be left out. Pulse reloads a theme the moment you save one of its files, so you can watch changes as you make them.

color.ini

Colors use Spicetify's names, so Spicetify color schemes work as they are. Missing keys are worked out from the others.

[Dark]
main               = 0b0b0e   ; background
sidebar            = 0f0f13
player             = 0f0f13   ; player bar
card               = 16161b
highlight          = 1d1d24   ; hovered rows
highlight-elevated = 24242d   ; selected rows
border             = 2c2c36
text               = ededf1
subtext            = 9696a4
text-faint         = 80808e
button             = 7c3aed   ; accent: buttons and sliders
button-active      = a78bfa   ; accent for text and icons

Pulse checks that text stays readable: when a color pair falls below the WCAG AA contrast level, Settings → Themes shows it under Theme notes.

user.css

A small part of CSS for named parts of the window:

PartsProperties
.sidebar .header .hero .player-bar .card .track-row .play-button background, color, border, border-color, border-width, border-radius, padding, font-size, font-weight, text-transform: uppercase
:root { --radius-sm: 8px; --radius-md: 12px; --radius-lg: 16px; }
.card { background: var(--spice-card); border-radius: 14px; }
.play-button { background: var(--spice-button-active); color: var(--spice-main); }

Colors can be #rrggbb, rgb(), rgba() or var(--spice-KEY). Anything Pulse doesn't support is skipped, and Settings → Themes lists what was skipped.

theme.toml

name = "My Theme"
author = "Me"
description = "What it looks like"

[layout]
sidebar = "full"           # or "icons"
hero = "banner"            # or "fullbleed": a full-width artist photo
player = "centered"        # or "controls-left"
now_playing_art = "bar"    # or "sidebar-large"
inset = false              # true: the main area floats as a rounded panel
backdrop = false           # true: soft glows in the playing song's colors

With backdrop on, Pulse works out the main color of the playing song's cover (once per song, in the background) and fills the main area with slow-moving glows in that color.

Accounts

A Pulse account is free and optional. You need one to make playlists public and to have a profile people can find. Everything else, including your whole library, works without one.

Creating an account

Pulse offers to make one the first time it opens (press Not now to skip). You can make one later in Settings → Account → Create account. You choose:

  • A username: 3 to 20 letters, numbers, _ or .. It's public: it's on your profile and on the playlists you share.
  • An email address: required, and only used to send you a code if you forget your password. It's never shown to anyone, and one email can have one account.
  • A password: at least 8 characters, and it can't contain your username.

Accounts made before email addresses were needed are asked to add one the next time Pulse opens. Until they do, the only other choice is to sign out.

Signing in

Sign in with your username or your email address. You stay signed in on that computer for 90 days. After 10 wrong passwords, signing in to that account from your connection pauses for 15 minutes.

If you forget your password

  1. In the sign-in window, press Forgot password?
  2. Enter your username or email address and press Send code.
  3. Pulse emails you a 6-digit code. If it isn't there in a minute, check your spam folder.
  4. Enter the code and a new password. The code works for 15 minutes and for 5 tries. After that, press Send a new code.

You're signed in with your new password, and signed out on your other computers.

Managing your account

In Settings → Account you can see your profile, change your email address or password (both ask for your password first), sign out, or delete your account. Deleting it removes your profile and every playlist you made public, right away. Your library on your computer stays.

Sharing playlists

Open one of your playlists and press Make public. Pulse copies its link, which opens in Pulse or on this website. Changes you make to the playlist are uploaded by themselves. Make private takes it down again. Songs from your Music folder are never uploaded.

Signing in on the website

You can also sign in on this website, under Your account (the person icon at the top): change your email or password, edit your profile, make playlists private, reset a forgotten password, or delete your account. New accounts are made in the app.

What the server keeps

Accounts live on a small server (a Cloudflare Worker and its database). It keeps your username, your email, your profile text, the playlists you made public, and a salted hash of your password, never the password itself. Signing in stores only a hash of each sign-in key. Reset codes are emailed through a mail service and stored only as a hash. A public playlist that three different people report is hidden. The server code is in server/.

Your data

The full details are in the Privacy Policy.

Unless you make a Pulse account and share playlists, nothing you do in Pulse leaves your PC. Everything it keeps is in %APPDATA%\pulse-player:

  • your likes, playlists, recently played songs, profile and settings, plus a spare copy of them (library.ron)
  • backups of your library in backups: one each day you use Pulse (the seven newest are kept), and any you make yourself in Settings → Your data
  • songs you've played recently, so they start at once next time (in the cache)
  • if you're signed in, your sign-in key (in account.json)
  • your themes
  • songs you download for offline listening (in offline; Settings → Storage lets you choose another place)
  • yt-dlp and Deno, and a cache of temporary files (Settings → Storage shows its size and can clear it)

Pulse also plays the music files in your Windows Music folder if you turn on Show Local Files in Settings. The only places Pulse talks to are the ones it gets music from: Deezer for song info, YouTube for audio, iTunes for missing covers, LRCLIB for lyrics, Google for search suggestions, GitHub for playback tools and updates, and the Pulse accounts server if you use an account. Discord status, when you turn it on, talks only to the Discord app on your PC (the official app, or Legcord or Vesktop with Rich Presence (arRPC) turned on in their settings; the Discord website can't show it). Uninstalling keeps your folder, so reinstalling picks up where you left off; delete the folder to remove everything.

If your library file gets damaged

Pulse saves your library every half minute. If your PC loses power or Pulse is closed in the middle of a save, the file can be cut off. When Pulse can't read it, it opens the spare copy instead, which is saved in a way that's never left half-written. If that's missing too, it restores the newest backup. Either way Pulse tells you what happened, and keeps the damaged file in backups. You can also restore any backup yourself in Settings → Your data.

Your playlists can be shared as a one-line code that contains just the list of songs. Nothing is uploaded: the code itself is the playlist.

Keyboard shortcuts

ActionKeys
Play / pauseSpace
Next / previous songCtrl + → / Ctrl + ←
Volume up / downCtrl + ↑ / Ctrl + ↓
MuteM
Shuffle / repeatS / R
SearchCtrl + K
LyricsL
Mini playerCtrl + M
Gaming Mode on / offCtrl + G
Back / forward between pagesAlt + ← / Alt + →, or your mouse's side buttons
Move between buttons and songsTab / Shift + Tab
On a song: play / add to queue / play nextEnter / Q / N
Select several songsCtrl or Shift + click, Ctrl + A for all
Remove selected songs from your playlistDelete
QuitCtrl + Q

Right-click any song for more: like it, add it to a playlist, see its credits, download it, or copy a link to share.

Building it yourself

You need Rust. On Windows, its installer offers to set up the Visual Studio C++ Build Tools too; say yes.

git clone https://github.com/mercy123xz/Pulse.git
cd Pulse
cargo run --release

The first build takes a few minutes; the app ends up at target\release\pulse.exe. Run the tests with cargo test. To make the installer, install Inno Setup and run:

iscc /DAppVersion=1.2.0 installer\pulse.iss

Where things are in the code

FileWhat it does
src/audio.rsThe audio engine: two decks, streaming in pieces, preparing the next song
src/dsp.rsEqualizer, mono, fades and silence detection
src/youtube.rsInstalling and updating yt-dlp and Deno, matching songs to videos, getting audio links
src/deezer.rsSong info, artwork, charts, artist and album pages
src/import.rsImporting playlists from YouTube, Spotify and SoundCloud
src/suggest.rsSearch suggestions while you type, and how they're ranked
src/audiocache.rs, src/artcache.rsSongs and covers kept on disk so they load at once
src/backup.rsBackups, the spare copy of your library, and recovering a damaged one
src/lyrics.rs, src/discord.rs, src/update.rsLyrics, Discord status, and checked, signed updates
src/account.rs, src/ui/online.rsAccounts: signing up and in, password resets, public playlists, profiles
server/The accounts server (a Cloudflare Worker with a D1 database) and its tests
src/app.rsPages and history, the queue, shuffle and repeat, your library, saving
src/ui.rs, src/widgets.rsEverything you see, and the custom-drawn pieces it's made of
src/themes.rs, assets/themes/The theme loader and the built-in themes
installer/pulse.issThe Windows installer
.github/workflows/The automatic builds, releases and this website

If something goes wrong

"Windows protected your PC"

Windows SmartScreen shows this for apps that aren't widely downloaded yet, and Pulse is still new. Click More info, then Run anyway. It can show again for a new version, until more people have installed it.

Pulse is open source, and every installer is built in public on GitHub, so you can check exactly what you're running. You can also see the 1.3.0 installer's scan by 70+ antivirus engines on VirusTotal.

The first song takes a while

Pulse is downloading its playback tools (about 70 MB, once). The player bar shows the progress. After that, songs start in a few seconds.

A song won't play

YouTube may not have a full version of it, or YouTube changed something and yt-dlp hasn't caught up yet. Pulse updates yt-dlp daily, so trying again later often works. Pulse skips to the next song after a failure.

Pulse says my library file was damaged

Pulse has already put it right, from the spare copy (nothing lost) or the newest backup (anything since that backup is missing). If a backup is missing something you need, Settings → Your data lists every backup to restore from. The damaged file is kept in the backups folder.

Covers are missing

Pulse shows a music note in place of a cover it couldn't download, usually because you're offline. Covers come back when you're online again.

The window flickers or stays blank

Turn off Settings → Compatibility → Enable hardware acceleration and restart Pulse. It will draw with Windows' software renderer instead.

I can't sign in

Check you're using the username or email address you signed up with. If you forgot your password, press Forgot password? in the sign-in window (see Accounts). If you've tried too many times, wait 15 minutes.

The reset code didn't arrive

Look in your spam folder. A code only goes to the email address on the account, and only 3 codes are sent per hour. If your account has no email address, no code can be sent: open an issue and ask for help.

Still stuck?

Ask in the Pulse Discord (there's a help forum and private support tickets), or open an issue on GitHub and describe what happened.