Spotifai

Goal

Build Spotifai, a polished macOS music discovery app for someone who wants a Spotify-style way to browse charts and find audio they are allowed to play. Show popular tracks, albums, and artists, search only the public sources the person selects, and play a Deezer preview or a supported audio file from an authorized torrent. Explain the app’s network and sharing behavior plainly; a search result is not proof that the person has permission to play it.

Before you start, ask the person

1. Which public search sources should be selected when the app opens? (Default: ThePirateBay, KickassTorrents, Limetorrents, and TorrentProject when available.)
2. Should the home screen show popular tracks, albums, and artists from Deezer? (Default: Yes.)
3. How much disk space may the app use for cached torrent audio? (Default: 2 GB, with older cached data removed automatically.)
4. Where should the finished app be saved? (Default: the project’s release folder; install it in Applications only if asked.)

If the person is unavailable, use these defaults. Never ask for private-provider credentials or a music-service password.

Features

• Browse music: On launch, show Spotify-inspired shelves for popular tracks, albums, and artists using Deezer’s public chart endpoint https://api.deezer.com/chart/0?limit=50. Cache chart data for one hour and provide a Refresh button. If the service is unavailable, keep search and the player available and show a readable message.
• Show cover art and previews: Use only valid Deezer image URLs and Deezer’s available 30-second preview URLs. A missing image or preview gets a clear fallback; never imply a preview is a complete track.
• Search music: Provide a search field, Music category, and checkboxes for available public torrent-search-api sources. Search only selected providers, cap each provider request at 80 results, and use a 10-second timeout per provider. Map Music to Audio for ThePirateBay and to All for TorrentProject or Torrentz2 when those categories are available. Skip unsupported providers; keep results from successful sources when another source fails and name the unavailable sources.
• Keep results relevant: Normalize accents and punctuation in query and title text. For meaningful query words longer than two characters, require each word to appear as a whole title word. In Music searches, discard clear video or TV release labels such as episode codes, common video resolutions, WEB-DL, Blu-ray, and common video codecs. Rank exact phrase and leading-title matches first, then music-format cues such as FLAC, MP3, or discography, then seed count. If filtering removes everything, say no relevant results were found. These checks only improve search relevance; they do not verify rights, quality, or safety.
• Search from shelves: Clicking a track’s Find action searches its title and artist. Clicking an album or artist fills the search field and searches that title. Show search results directly below the search box and scroll to the results when the search finishes. Do not start playback just because someone browsed or searched.
• Play previews: Let the person start or pause a Deezer preview when one exists. If no preview is available, say so. A preview action must not search torrent sources.
• Play an authorized torrent result: Provide a distinct Play button. Only after the person clicks it, resolve and validate the magnet, connect to one torrent at a time, wait for metadata, and select supported audio files (mp3, m4a, aac, ogg, opus, wav, flac, aiff, aif). Do not download unrelated files. If no supported audio is present, explain how to choose another result.
• Stream and cache: Stream the selected audio through a local HTTP server bound only to 127.0.0.1, using byte-range responses so the player can seek. Store torrent pieces under the app’s macOS user-data folder, resume them on later playback, and keep the total cache at or below the chosen size (default 2 GB), removing least-recently-used stopped torrents first. Keep the active torrent until Stop or a different torrent is started. Explain that torrent playback may upload pieces to other peers while active.
• Show playback status: Show the track or torrent name, elapsed and total time when known, download progress, connected peers, and useful waiting or error messages. Distinguish waiting for metadata from waiting for peers and from an unsupported audio format. Let the person stop playback at any time.
• Make network use clear: Explain that Deezer receives chart and preview requests, selected public search providers receive search terms, and torrent peers receive the torrent connection and may receive uploaded pieces during playback. Do not add analytics, search-history storage, another proxy, private-provider logins, or unrelated network requests.
• Finish the Mac app: Use a custom Spotifai icon, keyboard-accessible controls, clear loading and empty states, and a Spotify-inspired visual style. Support system light and dark appearance and keep the layout usable in a narrow window. Do not register as the default magnet handler unless the person asks.

Constraints

• Use Electron with torrent-search-api 2.1.4 for source search and WebTorrent 3.x for streaming. Keep network, torrent, file-system, and cache work in the Electron main process. Give the renderer a small preload bridge; keep nodeIntegration off, contextIsolation on, and sandboxing enabled.
• Bind the stream server to loopback only and use an unguessable per-playback path. Validate magnet links before opening or starting playback. Escape all provider-supplied text before rendering it.
• Store preferences under one app-owned key with a schemaVersion; handle read/write failures and add migrations when the schema changes. Store the large torrent cache separately under the app’s user-data folder and enforce the configured limit.
• Only use the listed Deezer chart and preview endpoints and the public providers exposed by torrent-search-api. Do not collect private credentials, send search text to Deezer, or claim that any source result is licensed or verified.
• Keep a visible reminder to play only content the person is authorized to access. Make it clear that torrent playback can share downloaded pieces. Do not auto-play or start a torrent as a side effect of opening the app, browsing, searching, or previewing.
• Keep controls labeled for assistive technology, provide keyboard focus and visible focus styles, respect reduced motion, and support a compact layout down to 360 CSS pixels.

Build steps

1. Check macOS, Node.js, npm, and the available processor architecture. Ask the four questions above; use the defaults if the person is unavailable.
2. Create the Electron project, install the specified dependencies, add a restrictive preload bridge, and make a minimal window that launches before adding features.
3. Implement public-provider discovery and search in the main process. Add category mapping, per-source timeouts, partial-failure messages, placeholder-result removal, whole-word query filtering, Music video-release filtering, relevance ranking, and an 80-result cap.
4. Add the Deezer chart request and one-hour cache. Validate chart, image, and preview URLs before sending them to the renderer; add track, album, and artist shelves with working search actions.
5. Add preview playback, then add click-to-play torrent streaming. Validate magnets, select audio files only, serve byte ranges on loopback, report progress and peers, and stop or replace the active torrent cleanly.
6. Add persistent preferences with a schemaVersion, a size-limited resumable cache, safe cache cleanup, accessible states, system appearance support, and the network-use and rights notices.
7. Add the app icon and package a macOS .app into release/. Launch the packaged app and complete the acceptance checks. Install to Applications only when the person requests it.

Acceptance checks

• The packaged app opens as Spotifai, shows the browse shelves and search controls, and remains usable when Deezer is unavailable.
• With mocked results, a Music query for kraftwerk excludes a title such as The Simpsons S03E10 Burns Verkaufen der Kraftwerk 1080p DSNP WEB-DL, while a matching audio release remains. A multiword query with a missing meaningful title word is filtered out. Exact and leading-title matches rank above incidental mentions.
• Selecting only one provider sends the search to that provider alone. A failed or unsupported provider does not hide results from responding providers; if all sources fail, the app shows a clear error. Empty searches do not contact providers.
• Clicking a chart track’s Find action, an album, or an artist sets the intended search phrase; after searching, results are visible directly below the search box. Browsing and previewing alone never start a torrent.
• A Deezer preview plays only when a valid preview URL exists. Unsupported preview or torrent audio shows a clear message.
• A Play click starts one selected audio file from an authorized test torrent, reports metadata/peer/download status, supports seeking, and streams only over loopback. Stop ends active network activity while retaining cache for resuming.
• Cache cleanup keeps stored torrent data within the chosen limit and removes older stopped entries before active playback data. Preferences survive restart and load safely if stored data is malformed or from an older schema.
• The UI works by keyboard and assistive labels, supports light and dark appearance, and remains usable at 360 CSS pixels. The app explains which services receive requests, that torrent playback may upload pieces, and that the person must have permission to access the audio.

Hand-off to the person

Tell them:

• Where the packaged app is and how to open it. If they asked for installation, confirm the Applications location and suggest adding Spotifai to the Dock.
• How to browse, search, start a preview, and choose a separate Play action for an authorized torrent result.
• Where the torrent cache is (~/Library/Application Support/Spotifai) and that removing stopped cached data frees disk space; explain the configured cache limit.
• Deezer and selected search providers receive requests for their features. Torrent playback connects to peers and may upload pieces while active. Search results are not a rights check, so they should play only music they are authorized to access.
• Which defaults were used and how to change selected providers and cache size.