An open-source Windows music player with a private, full-featured phone remote for your local music library.

Your music library may already be stored on your computer, but controlling it from another device is usually a feature reserved for streaming platforms. Toph Player brings that experience to your own downloaded music—without uploading your files or requiring a cloud service.

Choose a music folder on your Windows computer and Toph Player will scan it, including all subfolders. Then connect a phone on the same Wi-Fi network to search your library, control playback, seek through tracks, adjust the volume, manage the queue, and access favorites and playlists. The audio continues to play through the computer and its selected output device while the phone acts as a responsive remote control.

Everything stays on your devices and inside your local network.

• Plays your existing local music files—no upload or music subscription required
• Recursively scans the selected folder and all of its subfolders
• Provides a complete browser-based phone remote on the same local network
• Keeps desktop and mobile playback state synchronized in real time
• Works with Android browsers and iPhone Safari
• Stores the library index, favorites, playlists, artwork cache, theme, and settings locally
• Open source under the MIT License

• Recursive scanning of the selected music folder
• Support for MP3, FLAC, WAV, M4A, AAC, OGG, Opus, and WMA files
• Automatic extraction of title, artist, album, duration, and embedded cover artwork
• Library views for songs, albums, artists, favorites, and playlists
• Fast search across song titles, artists, and albums
• Manual rescan after adding, removing, or changing music files
• Current library-folder path displayed in desktop Settings
• Safe library switching that clears stale tracks, queue entries, favorites, and cached artwork from the previous folder

• Play, pause, previous, and next controls
• Seek to any position in the current track
• Volume control from desktop or phone
• Shuffle mode
• Repeat off, repeat all, and repeat one
• Select an audio-output device
• Play now, Play next, and Add to Now Playing actions
• Reorder the active queue with drag and drop on desktop and mobile
• Automatic synchronization of track, playback position, volume, and queue state

• Add or remove tracks from Favorites
• Create persistent playlists
• Add tracks to existing playlists from desktop or mobile
• Browse playlists and start playback directly from the phone
• Keep favorites and playlists stored locally between sessions

• Connect by scanning a QR code or opening the displayed local address
• Secure pairing with a rotating six-digit code
• Responsive mobile interface with cover art and playback controls
• Searchable mobile library with Songs, Favorites, Albums, Artists, and Playlists tabs
• Queue browsing and reordering
• Real-time updates through WebSocket
• Heartbeat-based connection monitoring
• Clear disconnected state with a manual Reconnect action
• Mobile safe-area styling for modern iPhone displays
• Two built-in color themes: Earth and Purple

• Native Electron application for Windows
• Responsive React interface
• System-tray support: closing the window keeps Toph Player available in the tray
• Persistent settings and local application data
• Dedicated Connect Phone screen with QR code, pairing code, and available LAN addresses
• Artwork-based ambient background while music is playing

1. Toph Player scans the music folder selected on the Windows computer.
2. Metadata and embedded artwork are indexed locally.
3. A private LAN server becomes available while the desktop app is running.
4. A phone on the same Wi-Fi network pairs using the QR code and six-digit code shown by the desktop app.
5. Commands from the phone are sent to the computer in real time.
6. Music plays on the computer; the phone remains a remote control and library browser.

No audio files are uploaded to Toph Player, an external server, or a cloud storage service.

• Windows computer
• Node.js 20.19 or newer when running from source
• A phone and computer connected to the same private Wi-Fi or LAN
• Windows Firewall permission for Private networks when prompted

Download or clone the repository, open a terminal in the project directory, and run:

npm install
npm run dev

When the desktop app opens:

1. Go to Settings.
2. Select Choose folder and choose the root folder of your music library.
3. Wait for the recursive scan to finish.
4. Open Connect phone.
5. Make sure the phone is connected to the same Wi-Fi network.
6. Scan the QR code and enter the six-digit pairing code.

If the phone cannot open the address, allow Node.js and Toph Player through Windows Firewall for Private networks. VPNs, proxy tools, guest Wi-Fi, and access-point isolation may also prevent devices from communicating with each other.

# Start the development version
npm run dev

# Run TypeScript checks
npm run typecheck

# Create a production build
npm run build

# Build the Windows NSIS installer
npm run dist

The installer is created in the release/ directory.

TophPlayer/
├── electron/
│   ├── main.ts       # Electron lifecycle, scanner, LAN server, API, and media delivery
│   └── preload.ts    # Restricted bridge between Electron and the interface
├── src/
│   ├── App.tsx       # Desktop player and mobile remote
│   ├── styles.css    # Desktop and responsive mobile design
│   ├── main.tsx      # React entry point
│   └── types.ts      # Shared application types
├── SECURITY.md       # Security policy and vulnerability reporting
├── LICENSE           # MIT License
└── package.json      # Scripts, dependencies, and Windows build configuration

Toph Player is designed for use on a trusted private local network.

• Music files remain on the host computer
• File-system paths are not exposed to connected phones
• Remote API, media, artwork, and WebSocket access require authentication
• The six-digit pairing code changes whenever Toph Player starts
• Five incorrect pairing attempts trigger a five-minute lockout for that client
• HTTP byte-range requests are validated before media is served
• Cover files are restricted to the application artwork cache
• Electron runs with context isolation, renderer sandboxing, and Node integration disabled
• Production responses include a Content Security Policy and additional browser security headers

Do not forward the local server port or expose Toph Player directly to the public internet. Please read SECURITY.md before publishing or deploying a modified version.

• The desktop application is currently Windows-first
• The desktop app must remain running for the phone remote to work
• Both devices must be able to communicate over the same local network
• Audio plays on the computer, not on the connected phone
• A publicly distributed Windows installer should be code-signed to reduce SmartScreen warnings

Issues and pull requests are welcome.

Before submitting a pull request, run:

npm run typecheck
npm run build

For suspected security vulnerabilities, do not open a public issue. Use the repository's private Security → Report a vulnerability form and include the affected version, reproduction steps, and potential impact.

Toph Player is released under the MIT License.

Toph Player was implemented and built with ChatGPT. Product direction, ideation, quality assurance, and project management were led by A-R-KH.