The vgmu usage guide

A complete reference for everything vgmu can do.

Tip: You can also find a quick in-app reference anytime under Settings → Help.

Contents

• Navigation
• Home
• Browse
• Search
• Library
• Album pages
• Playback
• Sound Lab
• Listening stats
• Likes
• Manager
• Downloads
• Sharing playlists and folders
• Transfer Hub
• Local Library import
• Backup & Restore
• Settings
• Interface styles
• Themes
• Discord Rich Presence
• Offline and errors

Navigation

vgmu has four tabs (Home, Search, Library, and Manager) plus a Settings button in the header of every screen (a gear, or sliders in PictoChat). There is no account or sign-in; everything works locally on your device from the moment you install the app.

A mini-player appears above the tab bar whenever a track is loaded, showing artwork, title/artist, transport controls, and a compact progress bar. Tap it to open the full-screen Now Playing player.

Tap the tab you're already on to return to its first page.

Home

Home starts with rows built from your own listening, each of which you can turn on or off under Settings → Interface style → Home:

• Greeting: a short hello for the time of day on the first visit after vgmu opens, which then rolls into the date
• Continue listening: the track you paused, with time left, where it plays from, the next three tracks, and a Resume button
• Jump back in: the collections you played most recently
• New in your Library: albums you saved and playlists you made recently
• Your Liked Tracks: your latest likes
• Re-discover: liked tracks you haven't played in two weeks
• Because you played: more from the series of an album you played recently
• Trending now: what people are viewing on the catalog

Below those, Home shows three sections pulled live from the online catalog, which you can turn off in the same place:

• Latest: recently added soundtracks
• Top 40: currently popular albums
• Most Favorites: all-time favorite albums

Each card shows the album title and a subtitle (type and year, when known). Pull down to refresh manually at any time.

Automatic refresh is Wi-Fi-first by default. Home only refreshes itself over cellular data if you enable Settings → Network → Refresh Home on cellular. If a refresh fails, Home keeps showing your last successful data along with an "Updated {time}" note so you're never left with a blank screen.

Tap Browse in the header to jump to more discovery options, or the chart button to see your Listening stats.

Browse

Browse offers on-demand preset lists that load only when you pick one:

• All-Time Top 100
• Last 6 Months Top 100
• Top 100 Newly Added
• Currently Viewed: albums other listeners are currently browsing

There are also two quick-discovery shortcuts:

• Random Album: jumps straight to a random album page
• Random Song: jumps straight to a random track

If a preset can't load, Browse says there was a problem loading it, and that it may have changed or been removed from the catalog. Your Library isn't affected.

Search

Search looks up albums and soundtracks, not individual track titles, because track-level results from the catalog aren't reliable enough to show. Type at least 2 characters; results load automatically about 300ms after you stop typing.

Filters (tap a chip to open its picker):

• Sort
• Album type
• Year
• Platform

Filter options are populated from whatever the catalog actually offers for your current search, so they may vary. Use the Reset filters chip to clear them all. Results load more as you scroll (with a manual "Load more" button as a fallback), and a result count is always shown.

Library

Library is your personal collection. It's organized into a few kinds of entries:

Built-in collections (always present)

• Liked Tracks: every track you've hearted
• Offline Library: every track that's been downloaded and verified for offline playback
• Local Library: audio files you've imported from your device (see Local Library import)

These three can't be deleted, since they represent live state rather than something you created.

Things you create

• Playlists: tap Create (+) → Create Playlist, give it a name, and optionally a description and cover photo. Add tracks from any album page, search result, or the player's queue menu. Playlist names must be unique, and vgmu warns you if the name is already taken.
• Folders: tap Create (+) → Create Folder to group playlists, saved albums, and single tracks under one name, description, and cover photo. Pick which albums and playlists belong to it using a searchable picker with A-Z section headers, artwork thumbnails, and filter chips for Albums, Playlists, and Downloaded. To add one track, use Add to folder in its menu (Console and PictoChat) or its folder icon (Clean). A folder page lists its playlists, albums, and tracks in labeled sections, with filter chips for All, Playlists, Albums, Tracks, and Downloaded, and its search covers all three. Deleting a folder never deletes what's inside it. Folder names must also be unique.
• Saved Albums: any album with at least one track saved to your library appears here automatically.

Organizing your Library

• Filter chips: All / Playlists / Albums / Folders / Downloaded
• Search within your library
• Sort: Recently Played or Title. Playing a collection inside a folder updates the timestamp for both the collection and the parent folder
• View: list or grid
• Pin: long-press a collection → Collection options → Pin, to keep up to 8 favorites at the top of the tab
• Delete/Unsave: long-press → Delete (for playlists/folders) or Unsave (for albums). Deleting a playlist or folder removes only the organizational grouping, never the underlying tracks, your likes, or any downloaded files.
• Shared with You: the people button beside the list and grid toggle opens what friends have sent you (see Sharing playlists and folders). The Shared filter chip lists the playlists you've added from them.
• Hide items already in a folder: on by default (Settings → Library), it removes albums and playlists from the main Library list once they belong to a folder, so they only show up inside that folder.

Editing playlists and folders

Open a playlist or folder and tap Edit to change its name, description, and cover photo, or to delete it. Renaming to a name already used by another playlist or folder isn't allowed. Tap a custom cover on its page to see it full size, then hold it to save it to Photos or Files; this also works for Liked, Offline, and Local Library.

• Playlists: tap Add tracks inside the editor to search your library and select tracks to add. To take one track out, open its menu inside the playlist and choose Remove from playlist (Console and PictoChat). In the playlist and folder pickers, anything that already holds the track says Already added and has a Remove button.
• Folders: tap Add items inside the editor to open the same searchable, filterable, A-Z-sectioned picker used at creation time, and choose which albums and playlists belong to the folder.

Closing an editor with unsaved changes asks whether to keep editing or discard them. Nothing is saved until you tap Save.

Album pages

Every album page offers:

• Play album: starts playback from the first track. Press and hold Play to add every track to the playback queue instead; a confirmation appears when adding 100 or more tracks. The same long-press works on playlists, folders, and Local Library pages.
• Save album: bookmarks it into your Library
• Download album: queues every track for offline saving
• Per-track rows, each with its own play, like, add to queue, add to playlist, add to folder, and download actions
• A track search that filters the list. While a search is active, playback follows it: tapping a track, or Play album, plays just the matching tracks, and Next Up holds those results instead of the whole album. The same applies to playlist and folder pages.
• A gallery of alternate cover art, when the catalog provides more than one image
• An "album information" panel with additional metadata
• The album's description. In Console and PictoChat it shows right on the page; in Clean, tap the album's title area to reveal it

Playback

Mini-player and full player

The mini-player (bottom of screen) gives you play/pause, previous/next, and a compact seek bar. Tap it to open the full Now Playing screen, which adds:

• Large artwork with swipeable transitions between tracks
• A full seek bar
• Like (heart): a quick tap likes the track; press and hold the heart to add the current track to a playlist instead (the heart pulses to confirm), then pick an existing playlist or create a new one
• Shuffle toggle
• Repeat, which cycles Off → Repeat All → Repeat One (a small "1" badge shows when repeat-one is active)
• Queue button, opening the full queue view
• Sliders button, opening the Sound Lab
• Swipe the screen down to dismiss it back to the mini-player
• Tapping the title/artist jumps you to the album, playlist, or folder the current track is playing from, scrolling straight to that track and highlighting it. When you're playing a whole folder, it opens the album that holds the track inside that folder.

Queue and Next Up

vgmu keeps two separate lists:

• Queue: tracks you've manually added; these always play first
• Next Up: the rest of the current context (the album, playlist, or search results you were browsing), playing automatically after the Queue is empty

Both lists load in batches of 100 tracks at a time to keep the queue responsive, even with very large collections. Section headers show the total count (e.g. "Queue (350)"), and a "+N more tracks" indicator appears when additional tracks are waiting to load. The next batch loads automatically as you play through them.

From the queue view you can reorder tracks, remove them, clear the queue, or promote an upcoming "Next Up" track into your manual queue. When tracks are still pending beyond the loaded batch, the clear button offers a choice between clearing the loaded tracks or the entire queue including all pending tracks.

Shuffle reshuffles the Next Up list; turning shuffle back off restores the original order. Shuffling a folder that holds several albums mixes all of their tracks together, the very first track included, rather than shuffling one album at a time.

Background and lock-screen playback

Playback continues when you close or minimize vgmu, and when your device is locked. Your device's lock screen and notification shade show the current track's title, artist, album, and artwork, with working play/pause and next/previous controls. (Seek-forward/seek-backward buttons are intentionally not shown on the lock screen.) Bluetooth and wired headset media buttons work the same way.

Your queue, current track, and playback position are saved automatically and restored the next time you open the app.

Sound Lab

The Sound Lab changes how every track sounds. Open it from the sliders button in Now Playing, or from the Sound Lab tile in Manager, and turn it on.

• Presets: Slowed + Reverb (0.8× speed with reverb) or Nightcore (1.25× speed), one tap each. Off resets speed, pitch, and reverb.
• Speed: from 0.5× to 1.5×.
• Pitch: Linked pitch follows speed like a record player; Independent sets pitch on its own, up to 12 semitones up or down.
• Reverb: a Mix slider that adds space to the sound.
• Equalizer: Bass, Mid, and Treble, each up to 12 dB up or down, with a Reset button.

Effects work on downloaded and streamed tracks, and stay on for every track until you turn the Sound Lab off. Your settings are remembered for next time and included in backups. While it's on, a streamed track downloads whole before it plays, so it can take a moment longer to start. Reverb fades in a moment after a track starts; the Sound Lab shows Adding reverb… meanwhile. Tracks longer than 10 minutes play without effects.

Listening stats

Tap the chart button at the top of Home to open Stats. Pick Week, Month, Year, or All time for a short recap you tap through: time listened, your top games and tracks, your busiest day, longest streak, peak hour, and new games. Tap Skip to go straight to the summary, where you can open a top game or play one of your top ten tracks. Its Listening time chart shows the time above each bar; in Month, tap a bar to see that day's time.

A track counts as played once you've listened for 30 seconds, or half of a shorter track. Your play history stays on your device and is included in backups.

Share your recap

In Stats, tap Share to make a story-sized card in your interface style. Choose what it shows (highlights, top games, top tracks, and a listening chart), and add up to three photo or GIF stickers you can drag, pinch, and turn. Then tap Share image, or Share GIF for an animated card. The preview shows progress while the card is made (closing the sheet cancels it), and a notice confirms when it's shared or saved to Photos. The file is named vgmu_stats with the date.

Likes

Tap the heart icon on any track row or in the full player to like it. Liking a track also saves its parent album to your Library if it isn't already saved. Liked tracks show up in Library → Liked Tracks; tap the heart again to remove one.

Manager

The Manager tab holds the tools that look after your music, as four tiles:

• Sound Lab: speed, pitch, reverb, and the equalizer (see Sound Lab)
• Transfer Hub: move music to and from a computer (see Transfer Hub)
• Backup: save or restore your Library (see Backup & Restore)
• Downloads: the download queue and history (see Downloads). The tile shows a count while downloads are in progress.

Manager's tab icon shows a live badge count of active, pending, and in-progress downloads.

Downloads

Manager → Downloads tracks everything you're saving for offline playback: Active, Pending, Needs Attention, and Completed. The clock button opens your Download History.

How the queue works

Only one download runs at a time, even if you've queued an entire album or playlist. Everything else waits its turn and shows a numbered position in the "Pending" list. Bulk album/playlist downloads are grouped together with an aggregate progress indicator.

Formats and quality

vgmu supports whatever formats the catalog offers per track: FLAC, M4A, MP3, and OGG. Set your preference in Settings → Download Quality:

• Best Available: automatically picks the highest-quality option actually offered for each track (FLAC → M4A → MP3 → OGG)
• FLAC Only, M4A/AAC, MP3, or OGG: force a specific format

Failures, retries, and rate limits

Recoverable errors (network hiccups, temporary source unavailability, timeouts, and rate limits) are retried automatically up to 3 times. If the source specifically rate-limits a request, vgmu shows a live countdown next to the job ("Waiting to retry · Ns") and retries exactly when the countdown reaches zero, rather than guessing.

Downloads that fail for other reasons (like a chosen format no longer being available) can be retried manually, with a prompt to pick a different format if needed. Failed jobs can be cleared individually or all at once.

Pausing and cancelling

You can pause and resume the active download, or cancel just the current track vs. the entire remaining batch.

Completion and history

Finished downloads appear in a "Completed" section. Tap a batch to see its tracks, then play one or check its format, size, and when it finished. Tap Done to acknowledge them, after which they move into a Download History you can review later. You control how long history entries stick around in Settings → Download History. Every file is checksum-verified before it's counted as successfully saved.

Sharing playlists and folders

Send a playlist or a whole folder to a friend. Only the list of tracks travels, never audio: whoever opens it streams the tracks from the catalog, or downloads them as usual.

• Share: open one of your playlists or folders and tap the Share button. Add your name if you like, then pick Share link to send a link by Messages, email, or anything else, or Share file to send a small .txt file, which Discord and other chat apps can preview. Include the cover adds the playlist's or folder's custom cover to the file (links can't carry it). A link is sent with a line naming what it is, like Check out my vgmu playlist "Road Trip".
• Tracks from your own files can't be shared and are left out; the sheet says how many. A playlist made only of your own files points you to Transfer Hub to send the music itself.
• Opening a link shows a page with the playlist or folder and an Open in vgmu button. Without vgmu, that page offers the download instead.
• Opening a file: open a shared .txt file from Files, Messages, or a chat app and choose vgmu, or use Open a shared file… in Shared with You. It's plain text, so without vgmu it still shows the track list. Older .vgmu and .vgmu.txt files still open, and a .vgmu file opens straight away when you tap it in Files. vgmu now appears under Open with for text files; any other text file just gets a message saying it isn't a shared collection.
• Shared with You: everything sent to you lands here as a card, kept apart from your own playlists until you add it. Open it from the people button in Library; its badge counts what you haven't added yet. Open a shared file… reads a shared file saved in Files.
• Adding it: a shared playlist page shows who sent it, its tracks, and how many are already in your Library. Play streams it straight away, Add as a new playlist keeps it, and Add tracks… merges it into one of your playlists without repeating tracks. A shared folder offers Add as a new folder, which makes the folder and its playlists and saves its albums. If every track is already in your Library, vgmu asks before adding it.
• Deleting: the trash button on a card, or Delete on its page, removes it along with the playlist or folder you made from it. Saved albums, likes, and downloads stay, and a playlist you merged it into is never deleted.

Transfer Hub

Manager → Transfer Hub gathers every way music moves between this phone and a computer.

Wi-Fi Transfer

1. Tap Start. vgmu shows an address and a four-digit code.
2. On a computer on the same Wi-Fi, open the address in a web browser and enter the code.
3. Send to your phone: drop music files or whole folders onto the page, or use Choose files / Choose a folder. MP3, FLAC, M4A, and Ogg files go into Library → Local Library under "Wi-Fi Transfer", with their tags and covers.
4. Get from your phone: every downloaded album and playlist is listed. Use Download all, open one to download single tracks, or tick tracks for Download selected. With Save as one .zip ticked, you get one download that opens into a folder named after the album or playlist; untick it for separate files.

You can keep using vgmu while Wi-Fi Transfer runs: a banner above the mini-player shows the code and has Stop. The screen stays on, and transfer stops when you leave vgmu. Ten wrong codes stop it, and you start again for a new code. Some school, office, and hotel networks keep devices from reaching each other; if the page won't load, try a home network or your phone's hotspot.

Faster by cable: plug the phone into the computer with a cable, and a second address appears, By cable · faster, which skips the router. If it doesn't, turn on Personal Hotspot (iPhone) or USB tethering (Android) with the cable plugged in.

Export albums or playlists

Export copies downloaded albums and playlists into a folder you choose (Files, a drive, or a shared folder), one folder per album or playlist. Files are named "01 - Title" or by title alone. Write tags and Embed cover art rewrite MP3 and FLAC tags so a computer's music player shows the right title, album, track number, and cover; M4A and Ogg files keep the tags they came with.

Import a folder and back up

Import a folder brings in files you copied by USB, AirDrop, or iCloud, through Local Library (see Local Library import). Back up your Library opens Backup & Restore.

Local Library import

Beyond downloading from the catalog, you can import audio files already on your device. Imported tracks appear in Library → Local Library, separate from catalog downloads. Enable Settings → Local Library → Scan nested folders if your music is organized into subfolders.

Use Refresh on an imported path to pick up new files. Refresh keeps working after vgmu is closed and reopened. On iPhone, folders added before version 1.0.7 need to be added again once with Add path; your imported tracks stay.

Backup & Restore

Manager → Backup lets you move your library to a new install or keep a personal copy.

• Export saves a backup file containing your playlists, folders, liked and saved tracks, custom cover art, listening history, and all settings and themes. Share or store it wherever you like (Files, AirDrop, cloud storage, and so on). vgmu doesn't upload it anywhere on its own. A confirmation appears once the export has finished.
• Import restores a backup file onto the current install. This replaces everything currently in your library and settings with the backup's contents, so it asks for confirmation before proceeding.
• Auto Backup saves a backup inside vgmu on a schedule you choose, from every time you open vgmu to monthly. The last five are kept, and a scheduled backup that matches the newest one isn't saved again. Use Restore from auto-backup to bring one back.
• Older versions: backups made with vgmu 1.2 or later can't be imported into older versions.
• What isn't included: downloaded audio files and folders imported from your device aren't part of the backup, since they stay tied to the install that made them. After importing, saved tracks re-download when opened and album covers refresh automatically; local-import tracks reappear in playlists but need to be re-imported to play. Music already downloaded on the phone you restore onto stays available.
• Device backups: downloaded music stays out of iCloud backups, because it can be downloaded again. After restoring an iPhone from iCloud, those tracks stream until you download them again, while Local Library imports come back with it. Android device backups don't include vgmu at all, so keep your own backup file.

Settings

Reached from the settings button on any screen.

Interface styles

vgmu has three interface styles. They share one Library, one set of downloads, and every other setting, so you can switch anytime under Settings → Interface style without losing anything. New installs start in Console; people updating from 1.0 keep Clean. See the Gallery for every screen in all three.

• Console: a home-menu look after the Wii, Wii U, and 3DS system menus: covers in white bezels on a dotted shell, one accent color, rounded type, and gentle motion. Settings → Colors has Appearance (System, Light, or Dark), fourteen accent colors (pink by default) plus any custom color, and a Background slider from darker to brighter. Colorful tab icons (off by default) gives Home, Search, Library, and Manager each their own color. Now Playing background picks what moves behind the player while music plays: floating music notes (default), the XMB wave, drifting Wii Menu style rings, or nothing. Track rows keep the heart inline and put Add to playlist, Add to folder, Add to queue, and Download in a ⋯ sheet. Inside your own playlist, that sheet also has Remove from playlist.
• PictoChat: the Nintendo DS chat app: pixel-cornered messages with name tabs, DS buttons that press in, DS ON/OFF switches, and pixel icons. Settings → Look has Appearance, your DS color (Console's pink by default, fifteen of the DS's user colors, or any custom color), the Background (the DS menu Grid, with a Grid size slider, or Paper lines ruled in your color), the Font (NDS12, the DS's own pixel font; DotGothic16, a finer pixel font that is easier to read; or M PLUS 1p, a plain sans), and Pixelate artwork, which draws album covers in square pixels with a Pixel size slider. Colorful tab icons (off by default) gives each tab its own DS color. Its Now Playing background is the DS boot screen's Squares (default), a faint Chat room of people typing and drawing, or nothing.
• Clean: the original, restrained vgmu look, with the color themes below and nothing animating.

In every style, Haptics turns tap feedback on or off and Crop artwork to fill (on by default) fills each cover frame; turn it off to see covers that aren't square whole. The launch splash plays in every style.

Themes

Themes apply to the Clean interface style. vgmu ships with dozens of built-in themes across several categories, previewed live before you apply them:

• Baseline (Simple UI): follows your device's system light/dark setting, with a selectable accent color. The theme picker's preview swatch reflects your chosen accent and light/dark mode
• Light & Classic, Dark & Classic
• Warm, Nature, Atmospheric
• Gaming: including console- and platform-inspired palettes

Popular presets include Dracula, Nord, Tokyo Night, Catppuccin (Latte/Mocha), Gruvbox, Solarized (Light/Dark), Rosé Pine, Monokai, One Dark Pro, Everforest, Material, and more. Pick one, preview it, and tap Apply theme to confirm.

Discord Rich Presence

An optional feature that shows what you're listening to on your Discord profile as a "Listening to" activity, including track title, artist, album, a live progress bar, and artwork. It is off by default.

Open Settings → Discord Rich Presence and tap Connect Discord. This uses Discord's official connection:

• Android: vgmu shows your track through the Discord app on your phone. Install Discord and sign in first; you don't enter a password or token in vgmu. If the status says vgmu can't reach the Discord app, open Discord, check you're signed in, and play a track again.
• iPhone: vgmu opens a Discord sign-in (in the Discord app if it's installed, otherwise a Discord web page) where you allow vgmu. vgmu keeps that sign-in in secure device storage, never your password. If the status says the sign-in expired, tap Connect Discord again.

A short Discord outage or lost connection doesn't sign you out: vgmu retries by itself. If Discord really does need a new sign-in, a small banner above the player says so, with Reconnect and a way to dismiss it.

Use manual token (advanced) is the older method: you paste your own Discord account token into Settings, and vgmu connects as your account over a method Discord does not officially support for this kind of use. It carries a real risk of action against your Discord account and is entirely at your own risk. If you were already connected this way, it keeps working; tapping Connect Discord switches you to the official connection and removes the saved token.

Presence is only shown while a track is playing or loading. Pausing, going idle, or hitting an error clears it immediately, so it never shows a stale "frozen" card. Disconnect stops it and removes the saved connection from your device. See PRIVACY.md for exactly what data this feature transmits.

Offline and errors

vgmu keeps your Library usable even when the online catalog isn't reachable:

• No connection: Home, Search, and Browse show a clear "connect to Wi-Fi or cellular data and try again" message; your Library stays fully available offline.
• Catalog temporarily disabled: shown if you've turned off Settings → Catalog Source; again, your Library remains available.
• Rate limited: any rate-limited request shows a live retry countdown rather than a generic error.
• Catalog changes: if something can't load, vgmu says there was a problem loading it, that it may have changed or been removed from the catalog, and to try again later or check for an app update. Your Library is unaffected.

In all of these cases, whatever you've already saved to your device keeps working normally.

Why do I sometimes see "rate limited" messages?

vgmu doesn't run its own music servers. It reads directly from a third-party online catalog, the same way your device would if you visited it in a browser. That catalog limits how many requests it will accept from a single device in a short period of time, mainly to keep its service stable and fair for everyone using it.

If you search, browse, or download a lot in quick succession (especially downloading a large album all at once), you may occasionally hit that limit. That's expected, not a bug. vgmu detects it automatically and shows a live countdown ("Waiting to retry · Ns") until it's safe to try again, then resumes on its own. You don't need to do anything; just let the countdown finish.

If rate limiting happens often, spacing out large downloads (rather than queuing many albums back-to-back) can help.

For setup help, see the installation guide. For problems not covered here, see Support, use the feedback form, or open an issue.