╔══════════════════════════════════════════════════════════════════╗
  ║                                                                  ║
  ║                       VGM WEB PLAYER                             ║
  ║                 Main features of the script                      ║
  ║                                                                  ║
  ╚══════════════════════════════════════════════════════════════════╝

  File .......... VGMWebPlayer.py
  Language ...... Python 3 + Tkinter (interface), pygame (audio and
                  gamepad), Pillow (images and graphic theme)
  VGM engine .... VGMPlay (NTSC version in app\ and PAL in app\PAL\)
  Emulator ...... Kega Fusion (app\kegafusion\), to play the games
                  whose music you are listening to
  Purpose ....... Retro-style offline player for the VGM soundtracks
                  of Sega Master System, Game Gear, SG-1000 and
                  SC-3000, with automatic library download.


  ──────────────────────────────────────────────────────────────────
   1. MUSIC LIBRARY
  ──────────────────────────────────────────────────────────────────

  •  Scans the "music" folder: reads the tracks inside ZIP archives
     and the standalone files.
  •  Supported formats: .vgm, .vgz, .wav, .mp3.
  •  Each ZIP is an album. Standalone files go into the
     "Standalone Files" album.
  •  Album and track names are made readable automatically
     ("AlexKiddInMiracleWorld-SMS" → "Alex Kidd In Miracle World SMS").
  •  "+ ADD" button to add files or ZIPs from any folder.
     Added files stay in the library even after a Sync Web, for the
     whole session.


  ──────────────────────────────────────────────────────────────────
   2. FILTERS
  ──────────────────────────────────────────────────────────────────

  •  Console filter: GG (Game Gear), SMS (Master System),
     SG (SG-1000), SC (SC-3000).
  •  Sound chip filter: FM (YM2413) or PSG.
  •  Filters can be combined. The "Reset" button clears them.
  •  Game and track counts are updated in the status display.


  ──────────────────────────────────────────────────────────────────
   3. THE THREE VIEWS
  ──────────────────────────────────────────────────────────────────

  GRID VIEW
  •  Cover grid that adapts to the window width.
  •  Cards drawn directly on the Canvas: even with more than 700
     games it is built in less than a tenth of a second.
  •  Covers loaded in a background thread, with a loading
     animation.
  •  "NEW" badge on albums downloaded in the last 5 minutes.
  •  Colors: green = album playing, yellow border = keyboard or
     gamepad selection, lime border = album playing and also
     selected, light green border = mouse hover.
  •  SHIFT+R shows or hides a soft red border around the albums
     that have no ROM in app\roms. The status line shows how many
     there are for a few seconds.
  •  When switching to the grid from another view, the album playing
     appears in the second visible row. With the arrow keys the view
     scrolls only when the selection reaches the edge of the visible
     area.

  TRACKLIST
  •  Album → track tree, with a cover preview on the side.
  •  Drawn "virtually": only the visible rows exist, so it stays
     instant even with about 9,000 tracks.
  •  Opens automatically on the album and track currently
     playing.
  •  Star ★ next to favorite tracks.

  FAVORITES
  •  Alphabetical list of favorites, with cover preview and a count
     on the view button.
  •  Removal with the Delete key or with right-click.

  All views stay built in memory: they are rebuilt only when the
  library or the filters change, so switching between them is
  instant. When you return to a view, it moves back to the track
  playing.


  ──────────────────────────────────────────────────────────────────
   4. PLAYBACK
  ──────────────────────────────────────────────────────────────────

  •  VGM/VGZ files are converted to WAV with VGMPlay and then
     played with pygame.
  •  Cache of converted tracks (app\cache): keeps the last 15,
     so listening to them again is instant. Cleared on exit.
  •  NTSC/PAL button: plays VGMs at 60 Hz or 50 Hz.
  •  LOOP repeats the current track. RAND enables random playback
     among the filtered tracks.
  •  Previous and next, including the automatic one at the end of a
     track, always start from the track playing, even if another
     track has been selected in the meantime.
  •  Progress bar: a click anywhere jumps there, or you can drag
     the handle. Playback resumes from there on release.
  •  Pressing Stop while a VGM is still loading, the track no longer
     starts right afterwards.
  •  MP3s use their real length and are not cut off before the
     end.
  •  Reads the GD3 metadata of VGMs (title, game, system, author,
     date, notes) in a collapsible panel.


  ──────────────────────────────────────────────────────────────────
   5. DISPLAY AND GRAPHICS
  ──────────────────────────────────────────────────────────────────

  •  LCD-style status display, with the track list of the album
     playing (▶ on the current track). Clicking a track in the list
     plays it.
  •  Slideshow of screenshots of the game playing (256×192), with
     adjustable speed from 1 to 7 seconds. If there are no
     screenshots, the album cover is shown.
  •  Animated bar equalizer with peak indicators.
  •  Vertical "stepped" VU-meter style volume slider:
       - click or drag to set the volume;
       - mouse wheel to adjust it in small steps;
       - top icon for maximum volume;
       - bottom icon for mute, which remembers the previous volume.
  •  Classic Winamp skin style theme:
       - "chassis" background with a violet-blue gradient, lighter at
         the top center, generated at the real size of the window;
       - inset frames around displays, lists and equalizer;
       - raised buttons with the gradient tinted by their color,
         brighter on mouse hover and with inverted relief when
         pressed;
       - the gradient is also the background of grid cards,
         tracklist, favorites, LCD and equalizer, and stays still
         while the content scrolls;
       - progress bar with a transparent inset groove, the part
         already played in soft green and a raised green handle;
       - vertical scrollbars in the same style: inset groove, raised
         arrows and handle, long handle so it is easy to grab;
       - secondary windows (Sync Web, Greetings & Links, messages)
         use the theme too.
  •  Colored title bar on Windows 11. The window appears already
     colored, with no white flash at startup.


  ──────────────────────────────────────────────────────────────────
   6. FAVORITES
  ──────────────────────────────────────────────────────────────────

  •  Right-click on a track (in Tracklist, in Favorites or on the top
     display for the track playing): add to or remove from
     favorites.
  •  Saved in favorites.lst next to the app, with relative paths.
     The app folder can be moved without losing favorites.
  •  "Atomic" file write (first a temporary file, then the
     replacement): an interruption does not corrupt it.


  ──────────────────────────────────────────────────────────────────
   7. LAUNCHING GAMES IN THE EMULATOR
  ──────────────────────────────────────────────────────────────────

  •  Right-click on an album (grid card, or album or track in
     Tracklist and Favorites): two entries to launch the game ROM
     with Kega Fusion:
       - "Launch ... in Grid View": embedded in the grid;
       - "Launch ... in External Window": in a separate window.
  •  On the gamepad, pressing A twice quickly launches the selected
     game embedded in Grid View. From Tracklist or Favorites the
     player switches to the grid by itself first.
  •  The ROM is looked up in app\roms\<album name>\ (the first .zip
     in the folder is used, even with a different name) and the
     emulator in app\kegafusion\Fusion.exe, both with paths relative
     to the app folder.
  •  The music is stopped before the game starts, even if the track
     was still loading.

  EMULATOR EMBEDDED IN GRID VIEW
  •  The Kega Fusion window is created already hidden, stripped of
     borders and menu and placed over the grid: it never appears as
     a separate window.
  •  The game area always keeps a 4:3 ratio and is centered.
  •  Decorative console frame (bezel) around the game, for Master
     System, Game Gear, SC-3000 and SG-1000. The "Bezel ON/OFF"
     button shows or hides it immediately. When it is on, the window
     width adapts to the frame.
  •  "✕ Close emulator" button above the game. Alternatively it
     closes by pressing + and - together on the gamepad.
  •  While playing, the grid icons, scrollbar and title are hidden.
     View switching (buttons, TAB and SHIFT+TAB), filters and
     playback controls are disabled. The volume stays usable.
  •  ESC is blocked when the player or the emulator is in the
     foreground, to stop Kega Fusion from going full screen and
     changing resolution. With other programs in the foreground ESC
     works normally.
  •  When the emulator closes, the grid goes back to how it was.

  EMULATOR IN AN EXTERNAL WINDOW
  •  Kega Fusion opens like a normal program, as if launched from
     File Explorer, and closes the same way. The gamepad + and -
     combination is left to the game.

  IN BOTH CASES
  •  The player's volume slider also sets the volume of Kega Fusion
     in the Windows volume mixer (requires pycaw).
  •  The equalizer follows the real game audio: the output sound is
     only read (WASAPI loopback capture), without changing it or
     adding latency (requires PyAudioWPatch and numpy). Without these
     packages the bars stay still while playing.
  •  While the emulator is open the player ignores the other gamepad
     buttons, so music and view don't change while playing.


  ──────────────────────────────────────────────────────────────────
   8. ONLINE SYNCHRONIZATION (SYNC WEB)
  ──────────────────────────────────────────────────────────────────

  •  Downloads the missing soundtracks (ZIP) and icons from
     vgm.impulseinformatica.com.br.
  •  Checks the ZIPs already present and downloads damaged ones again.
  •  Downloads game screenshots from smspower.org, with 12
     parallel requests:
       - the FM/PSG variants of the same game share the same
         screenshots;
       - games without screenshots are marked and no longer
         checked again at every Sync.
  •  Downloads and extracts the VGMPlay engine only if it is missing.
     For the .7z it tries tar, then 7-Zip, then py7zr, in that order,
     and creates the PAL version by itself.
  •  Downloads with timeout and in chunks: CANCEL stops immediately,
     and an interrupted download leaves no incomplete files.
  •  Final summary with the new albums, the downloaded screenshots and
     any problems.
  •  On first launch without music or without VGMPlay it offers the
     synchronization by itself.


  ──────────────────────────────────────────────────────────────────
   9. KEYBOARD, GAMEPAD AND MOUSE
  ──────────────────────────────────────────────────────────────────

  •  Keyboard:
       - arrows and Enter to move and play in all views;
       - TAB and SHIFT+TAB to go to the next or previous view
         (Grid View ⇄ Tracklist ⇄ Favorites);
       - SHIFT+R in Grid View to highlight albums without a ROM;
       - Delete to remove a favorite.
  •  Quick search: type the beginning of an album or track name,
     even a whole word, and the item gets selected. The typed text
     is cleared after a 1-second pause.
  •  USB gamepad (read with pygame, through the SDL2 mapping
     database; recognized even if plugged in while the app is open):
       - D-pad or left stick to move (in Grid View also right and
         left);
       - A to play the selected album or track;
       - A twice quickly to launch the game embedded in Grid
         View, stopping the music;
       - B to pause and resume;
       - X to switch between NTSC and PAL;
       - L2/R2 for the previous/next view
         (Grid View ⇄ Tracklist ⇄ Favorites), read as analog axes
         with hysteresis;
       - L1/R1 for previous/next track;
       - + to turn RANDOM mode on or off;
       - + and - pressed together to close the embedded Kega Fusion.
     While the emulator is open the player ignores the other gamepad
     buttons, so music and view don't change while playing.
  •  Gamepad check mode: launching the program with
     "python VGMWebPlayer.py --pad-debug" the Command Prompt shows
     the recognized gamepad and the buttons read at every press.
  •  Mouse: click, double-click, right-click for favorites and
     emulator, wheel to scroll lists and grid and to adjust the
     volume.
  •  The full list of controls is in the files
     Docs\VGM Player Comandi_IT.pdf and Docs\VGM Player Controls_EN.pdf.


  ──────────────────────────────────────────────────────────────────
  10. RELIABILITY AND PERFORMANCE
  ──────────────────────────────────────────────────────────────────

  •  Background threads never touch the interface directly:
     updates go through a queue run by the main thread.
  •  The app always uses its own folder, even when launched from a
     shortcut or from another folder.
  •  At startup, temporary files left over from an abnormal exit are
     deleted.
  •  The console/chip classification of each track is computed only
     once. With these optimizations filters, tracklist and grid
     stay fast even with more than 8,500 tracks.
  •  The gradient background is recomputed only when the window size
     changes; when lists scroll it is only moved, at the same moment
     as the content, so it does not flicker.


  ──────────────────────────────────────────────────────────────────
  11. FOLDER STRUCTURE
  ──────────────────────────────────────────────────────────────────

     VGMWebPlayer.py (or .exe)
     favorites.lst                favorites (created automatically)
     music\                       soundtracks (ZIP) and single files
     Docs\                        controls guides (PDF) and this file
     GUI\
        icon.ico, alex_onigiri.gif, album covers
        bezel_*.png, gg_bezel_*.png,
        sc_bezel_*.png, sg_bezel_*.png        console frames
        ScreenShots\<game>\       downloaded screenshots
     app\
        vgmplay.exe, vgmplay.ini, zlib1.dll    NTSC engine (60 Hz)
        PAL\                                   PAL engine (50 Hz)
        cache\                                 converted tracks
        roms\<game>\                           ROMs for the emulator
        kegafusion\Fusion.exe                  Kega Fusion emulator


  ──────────────────────────────────────────────────────────────────
  12. REQUIREMENTS
  ──────────────────────────────────────────────────────────────────

     pip install pygame pillow
     (pygame is used both for audio and for the gamepad)
     Optional:
     pip install py7zr                to extract VGMPlay if the PC
                                      has neither 7-Zip nor a tar
                                      that opens .7z files
     pip install PyAudioWPatch numpy  equalizer that follows the
                                      game audio
     pip install pycaw comtypes       Kega Fusion volume set by the
                                      player's slider