PlayerVF
Full source wiki

PlayerVF developer documentation.

This page expands the wiki using the full feature document plus the real source structure in lib. It documents the app areas, files, classes, responsibilities, and the main functions used by each part.

12 Main wiki sections
94 Function index entries
lib Source tree documented
Python Backend overview included

Overview

PlayerVF is a Flutter music and video player. It supports local music scanning, audio playback, video playback, playlists, favorites, lyrics, audio effects, YouTube Music search/stream/download, local network sharing, Wi-Fi Direct sharing, metadata editing, cover art extraction, and deep appearance customization.

Configured platformsAndroid, Windows, and web are present in the repository structure.
State styleProvider and ChangeNotifier are used for app settings, player state, library updates, and page changes.
Playback stackMedia playback uses media_kit, media_kit_video, just_audio/audio_service integration, and Windows SMTC support.
HelpersPython code supports YouTube Music, downloads, thumbnails, subtitles, tagging, and media metadata work.

Repository stats

These numbers come from a fresh scan of superstilist/PlayerVf on GitHub: language percentages use GitHub byte totals, while file, character, and line counts use a shallow clone of the remote master branch at commit a045995.

Dart 90.25% 791,200 language bytes on GitHub.
Python 9.75% 85,432 language bytes on GitHub.
Tracked files 85 1,040,612 total tracked bytes; 59 files are text.
Text size 949,566 Text characters across tracked remote source files, with 27,565 lines.

Largest tracked extension groups

Extension Files Bytes Characters Lines
.dart47814,895814,78523,742
.png2690,93600
.py387,74587,7452,316
.lock132,74832,7481,051
.gitignore16,3306,330164
.yaml23,1623,162103
.md12,3432,343122
.txt21,1411,14127
.metadata199899831
download13143149

Website and wiki characters

wiki.html32,223 characters and 450 lines in the documented page file.
Listed site files60,705 characters and 1,587 lines across HTML, CSS, docs, and content files.
Other site files28,482 characters and 1,137 lines without wiki.html.
Stats dataSaved in content/repo-stats.json for reuse by tooling or future pages.

Architecture

The app is centered around MusicService. UI pages ask this service to scan, play, queue, shuffle, repeat, load lyrics, download from YouTube, update metadata, manage playlists, and persist state. SettingsModel owns persistent user preferences for appearance, paths, video behavior, decoders, and performance.

Directory map

  • lib/main.dart: app entrypoint, theme building, app shell, navigation, keyboard shortcuts, mini player, and player overlay.
  • lib/models: serializable state objects such as music, playlists, settings, lyrics, covers, and selected page state.
  • lib/pages: full screens for library, favorites, playlists, player, video, YouTube Music, sharing, settings, and appearance.
  • lib/services: playback, scanning, metadata parsing, sharing, YouTube, MusicBrainz, responsiveness, performance policy, and OS media controls.
  • lib/widgets: reusable UI pieces such as cards, player controls, cover art, audio effects, particles, glass containers, and video surfaces.
  • lib/python: desktop Python backend for YouTube search, stream resolution, download, subtitles, thumbnails, and metadata files.

Models

CoverSmall data object for extracted cover bytes/path and cover metadata.
LyricLine, LyricsDocumentRepresent timed and plain lyrics. activeIndexAt chooses the lyric line for the current playback position.
MusicCore track/media object: id, title, artist, album, path, cover, genre, duration, favorite status, play count, last played, and date added.
PlaylistUser/system playlist model with id, name, music IDs, createdAt, updatedAt, JSON import/export, and copy support.
PageStateSmall ChangeNotifier that stores selected high-level page: home, favorite, or playlist.
SettingsModelPersistent settings model for paths, theme mode, theme preset, particles, font, layout, view mode, decoder mode, video behavior, share backups, and performance.

Settings enums

  • ViewMode: card or list.
  • NavPosition: top, bottom, left, right.
  • ThemePreset: material, graphite, classic, fox, anime, azure, cosmic, sunset, midnight.
  • ParticleEffect: none, sakura, snow, stars, bubbles, rain.
  • DecoderMode: auto, software, hardware.
  • PerformanceMode: auto, quality, balanced, batterySaver, maxPerformance.

Main app

main.dart

The entrypoint initializes media playback, configures desktop behavior, installs a Windows keyboard assertion guard, and runs MyApp. The app creates SettingsModel and MusicService providers and builds a Material theme from settings.

main()Starts Flutter, initializes playback libraries, applies desktop setup, and launches the app.
MyAppProvides settings and music services, then builds themed app navigation.
_buildAppThemeCreates the app theme from preset, brightness, accent color, and glass intensity.
MainNavigationScreenMain shell for tabs, mini player, search, shortcuts, navigation dock, and full player overlay.

Main navigation responsibilities

  • Selects between Home, Favorites, Playlists, YouTube Music, and Share pages.
  • Handles play/pause, next, previous/restart, seek, volume, mute, and fullscreen shortcuts.
  • Builds top app bar, navigation dock, search bar, content area, and mini player.
  • Uses _MiniPlayPauseButton for responsive optimistic play/pause UI.

Pages

HomeScreen

Home/library smart playlist page. It builds responsive playlist and library layouts, square playlist cards, playlist collage artwork, add-playlist flow, empty state, and automatic grid counts.

FavoritePage

Displays favorite tracks with adaptive grid/list behavior and opens tracks through the music service.

PlaylistPage

Shows all playlists, an empty state, adaptive grid count, and playlist creation dialog.

PlaylistDetailPage

Displays songs inside one playlist, opens player from details, builds playlist collage artwork, calculates grid count, and supports playlist rename/edit dialog.

PlayerPage

Full audio player with cover-based background, hero artwork, metadata, playback controls, queue preview, more options, add-to-playlist dialog, track detail view, queue sheet, lyrics sheet, fullscreen lyrics, online lyrics search, custom lyrics search, and lyrics editing.

VideoPage

Full video player with local and YouTube video support, palette background, quality switching, subtitle tools, fullscreen video page, keyboard intents, fullscreen controls, local manifest loading, YouTube detail loading, and quick queue.

YoutubeMusicPage

Searches YouTube Music, runs bridge smoke test, downloads audio/video/subtitles, chooses download options, detects already downloaded audio/video/subtitle marks, streams results, and renders search panel/result tiles.

SharePage

Starts/stops local sharing, discovers devices, connects to remote devices, syncs selected tracks, pauses/resumes/cancels transfer, renders host card, connect card, device rows, track rows, transfer flow, and status messages.

SettingsScreen

Controls scanning, source paths, YouTube download path, cache clear, song gap, video settings, subtitle picking, decoder mode, performance mode, background blur, and folder import messaging.

AppearanceScreen

Controls theme preset, light/dark/system theme, particles, custom accent color, RGB sliders, nav position, font size, border radius, glass effect, view mode, card size, margins, and release sliders.

Services

MusicService

The central service owns library state, selected track, playback state, player backend, volume, queue IDs, shuffle/repeat, playlists, lyrics, audio effects, subtitles, video state, streaming state, snapshots, and saved playback state.

Main groups inside MusicService

  • Initialization: video controller, player binding, async settings/library load, backend callbacks.
  • Playback: play/pause/toggle, next, previous, seek, queue playback, restart, repeat, shuffle, completion behavior.
  • Media backend: opening local files, URLs, streams, downloaded videos, YouTube streams, and applying decoder settings.
  • Audio effects: enable/disable, equalizer, presets, pitch, speed, reverb, per-song/global mode, native Windows filters, MPV fallback filters.
  • Lyrics: sidecar lookup, manual lyrics paths, online LRCLIB search, custom queries, save/edit lyrics, active lyrics ownership.
  • Library: scan/import, merge remembered state, cover extraction, downloaded video quality collapse, favorites/stats/playlists persistence.
  • Subtitles: sidecar candidates, URL subtitles, local subtitle files, disable subtitles, and apply sidecar subtitle when present.

Other services

MusicScannerServiceScans paths, reads Android media hints, detects audio/video files, parses metadata, extracts cover art, and creates Music objects.
ID3ParserParses MP3 ID3v2/v1, APE, MP4/M4A, FLAC, cover art, duration, and filename fallback metadata.
CoverExtractorExtracts cover art from local files or assets next to bundled music.
CoverColorServiceCreates cover palettes for player/video backgrounds and fallback colors.
YoutubeMusicServiceSearch, download, stream, warm stream cache, resolve download directory, run Python/native helper, and convert errors into friendly messages.
LocalShareServiceLocal HTTP share server, discovery, manifest fetch, file transfer, pause/resume/cancel, duplicate checking, and safe filenames.
WifiDirectServiceAndroid Wi-Fi Direct permissions, discovery, connect, disconnect, stop discovery, and trust device IDs.
MusicBrainzTagServiceSearches MusicBrainz, scores tag matches, normalizes tokens, and returns selected recording metadata.
PlayerAudioHandlerBackground/OS media controls, media buttons, timeline, metadata, Windows SMTC guard, and external playback state.
PerformancePolicyDecides animation duration, particles, blur, cache scale, and visual cost by performance mode.
ResponsiveViewport scale helpers and extensions like 10.w, 10.h, and 14.sp.
web_folder_pickerWeb folder import implementation and stubs for non-web platforms.

Widgets

MusicCardTrack card/list row, context menu, track info, edit metadata, MusicBrainz tagging, cover picking, and add-to-playlist dialog.
PlaylistCardLarge playlist card with cover collage, context menu, and menu items.
SmallPlaylistCardCompact playlist tile with deterministic color by playlist id.
PlaybackProgressControlStable progress slider with bounded position and progress-to-duration conversion.
AudioEffectsMenuBottom sheet for speed, pitch, reverb, EQ presets, EQ bands, song/global scope, tone buttons, and reset actions.
CoverArtTextureShows local, network, blob, or fallback cover art; tries multiple network candidates.
GlassContainerReusable clipped blur/translucent panel with surface color calculation.
ParticleSystemAnimated sakura, snow, stars, bubbles, or rain particles with performance scaling.
StableVideoSurfaceKeeps video texture stable and schedules Windows texture resize.
SettingsDrawerCompact settings drawer for paths, YouTube download location, web folder messages, and import results.
FadeInUpAnimationSimple entrance animation wrapper.
ShowUpControlVisibility toggle wrapper for show/hide controls.

Python backend

lib/python/api.py supports desktop YouTube Music search, audio/video downloads, subtitles, thumbnails, metadata, safe filenames, duplicate-safe output paths, and stream resolution.

SearchItemNormalized search result data passed between Python and Flutter.
MediaDownloaderHandles detailed media download behavior, output naming, metadata, covers, and final library file selection.
Searchsearch_youtube_music returns normalized JSON search results.
Downloaddownload_youtube_music downloads audio/video/subtitles and returns downloaded file paths.
Streamstream_youtube_music resolves stream URLs, qualities, and subtitle data.
UtilitiesSafe filenames, MIME detection, thumbnail selection, high-quality thumbnail URLs, duration parsing, and progress events.

Data flows

Local scan flow

  1. User adds or updates a music path in settings.
  2. SettingsModel saves the path.
  3. MusicService asks MusicScannerService to scan.
  4. ID3Parser and CoverExtractor parse metadata and artwork.
  5. Old favorites, stats, and playlist identity are merged back.
  6. Library snapshot is saved and the UI updates.

Playback flow

  1. User taps a track or queue item.
  2. MusicService selects the track and prepares the player backend.
  3. Audio effects and decoder settings are applied.
  4. Playback starts and PlayerAudioHandler updates OS controls.

YouTube download flow

  1. User searches from YoutubeMusicPage.
  2. YoutubeMusicService calls Python or Android helper code.
  3. User selects audio/video/subtitle options.
  4. Backend downloads files and returns paths.
  5. Library refresh/import makes the files available in PlayerVF.

Sharing flow

  1. Host starts a share server.
  2. Receiver discovers or connects to the share server.
  3. Receiver fetches a manifest and selects tracks.
  4. LocalShareService downloads files with progress and duplicate checks.

Function index

This index is grouped from the real source files under lib. It focuses on named classes and main methods instead of generated/cache files.

Models

  • Cover
  • LyricLine
  • LyricsDocument.activeIndexAt
  • Music.toJson
  • Music.fromJson
  • Playlist.toJson
  • Playlist.fromJson
  • PageState.setPage
  • SettingsModel.loadSettings
  • SettingsModel.setThemePreset
  • SettingsModel.setParticleEffect
  • SettingsModel.setNavPosition
  • SettingsModel.setFontSize
  • SettingsModel.setBorderRadius
  • SettingsModel.setGlassEffect
  • SettingsModel.setAccentColor
  • SettingsModel.setViewMode
  • SettingsModel.setThemeMode
  • SettingsModel.addMusicPath
  • SettingsModel.removeMusicPath
  • SettingsModel.clearAllPaths

Pages

  • HomeScreen.build
  • HomeScreen._buildResponsiveLayout
  • HomeScreen._showCreatePlaylistDialog
  • FavoritePage.build
  • PlaylistPage._showCreatePlaylistDialog
  • PlaylistDetailPage._showEditPlaylistDialog
  • PlayerPage._buildControlsSection
  • PlayerPage._showQueueSheet
  • PlayerPage._showLyricsSheet
  • PlayerPage._searchLyrics
  • PlayerPage._editLyrics
  • VideoPage._loadLocalVideoManifest
  • VideoPage._loadYoutubeDetails
  • VideoPage._changeYoutubeQuality
  • VideoPage._showQualitySheet
  • VideoPage._showSubtitleSheet
  • YoutubeMusicPage._search
  • YoutubeMusicPage._download
  • YoutubeMusicPage._stream
  • YoutubeMusicPage._chooseDownloadOptions
  • SharePage._startSharing
  • SharePage._autoFindDevices
  • SharePage._syncTracks
  • SettingsScreen._addPath
  • SettingsScreen._pickSubtitleFile
  • AppearanceScreen._buildPresetButton
  • AppearanceScreen._buildAccentColorPicker

Services

  • MusicService._initializeAsync
  • MusicService._initPlayer
  • MusicService.setEffectsEnabled
  • MusicService.setEqualizerPreset
  • MusicService._applyAudioEffects
  • MusicService.setDecoderModes
  • MusicService.loadSubtitleFile
  • MusicService.loadLyricsForCurrent
  • MusicService.searchLyricsForCurrentOnline
  • MusicService.saveLyricsResultForCurrent
  • MusicService._tryFetchLyricsOnline
  • MusicService._handleTrackCompleted
  • MusicService._restorePlaybackStateIfNeeded
  • MusicScannerService.processPath
  • ID3Parser._parseMp3Tags
  • ID3Parser._parseMp4Tags
  • ID3Parser._parseFlacBlocks
  • ID3Parser.parseDurationFromFile
  • CoverExtractor.extractCover
  • YoutubeMusicService.download
  • YoutubeMusicService.stream
  • YoutubeMusicService.warmStreams
  • LocalShareService.startSharing
  • LocalShareService.fetchManifest
  • LocalShareService.pauseTransfer
  • WifiDirectService.ensurePermissions
  • MusicBrainzTagService.findBestTagForMusic
  • PlayerAudioHandler.updateNowPlaying
  • PlayerAudioHandler.skipToNext
  • PerformancePolicy.animation

Widgets and Python

  • MusicCard._showTrackInfoDialog
  • MusicCard._showEditMetadataDialog
  • MusicCard._autoTagWithMusicBrainz
  • MusicCard._pickCoverArt
  • AudioEffectsMenu.showAudioEffectsMenu
  • PlaybackProgressControl._progressFor
  • CoverArtTexture._buildDefaultCover
  • ParticleSystem._initParticles
  • StableVideoSurface._scheduleWindowsTextureResize
  • api.safe_filename
  • api.search_youtube_music
  • api.download_youtube_music
  • api.stream_youtube_music
  • api._collect_video_qualities
  • api._collect_subtitles
  • api._main
Note: the source contains many more private helper functions in the large player/video/service files. This wiki documents the full source areas and the main callable responsibilities, while avoiding raw code dumps.

Notes for future development

  • MusicService is very large and could eventually split into playback, library, lyrics, queue, effects, and persistence services.
  • Python desktop and Android helper behavior should stay aligned when changing YouTube search, stream, or download features.
  • Downloaded video manifests and subtitle metadata should be treated as stable formats once users have files on disk.
  • Settings are stored with SharedPreferences keys; renaming keys without migration can lose user preferences.
  • Library identity depends on IDs and file paths, so changing ID logic can affect favorites, playlists, stats, and resume data.
  • Audio effect behavior differs by backend and platform; Windows native filters and generic media_kit paths both need testing after changes.