Netflaix

Goal

Build Netflaix, a dark, cinematic macOS movie discovery app with a featured-film home screen, horizontal poster shelves, and simple top navigation. It searches public sources through torrent-search-api, sorts results by seeders, and lets the person copy or open magnet links. Add a shelf of popular films that have a released digital date using Radarr’s metadata service, with no personal TMDB token setup, and an in-app player that starts a video torrent only after the person clicks Play on a result. Search sources, the metadata service, image CDN, and torrent peers receive only the requests needed for their features; use the app only with content the person is authorized to access.

Before you start, ask the person

1. Which public sources should be selected when the app opens? (Default: ThePirateBay, Yts, 1337x, Torrent9, and Eztv when available)
2. Which search category should be selected initially? (Default: All)
3. Where should the finished app be saved? (Default: in the project’s release folder)
4. Where should downloaded video pieces be kept? (Default: the app’s macOS user-data folder, so downloads can resume and can be removed later)

Features

• Search sources: Provide a search field, category menu, and searchable public-source list. Search only checked providers. Select only providers marked public by torrent-search-api; show private providers as unavailable without asking for credentials.
• Compare results: Show each result’s title, source, size and available date. Sort by seeders from highest to lowest; missing seed counts appear as a dash and sort below numeric counts. Show peers when the source provides them.
• Handle categories: Offer All, Movies, TV, Music, Games, Apps, Books, and Anime. If a source does not support the chosen category or fails, keep valid results from other selected sources and explain when every source fails.
• Copy or open: Provide Copy and Open actions on every result. If the result has no magnet yet, ask the provider for it when the person clicks. Copy places the magnet on the clipboard; Open passes it to macOS to launch the person’s default torrent app.
• Streaming-style home: Use a dark charcoal background, restrained red accent, top navigation, a cinematic featured-film area backed by the most popular digital release in the feed, and a horizontally scrolling poster shelf. On narrow windows, keep navigation, search and poster cards usable without horizontal page overflow.
• Popular poster shelf: On launch, request the list from Radarr’s metadata endpoint https://api.radarr.video/v1/list/tmdb/popular in the Electron main process. Filter to movies with a valid DigitalRelease date on or before the current UTC date, preserving the feed’s popularity order. Map TmdbId, Title, Year, Popularity, DigitalRelease, and Images entries with CoverType Poster or Fanart. Show the poster, title, year, digital release date, and popularity score. Cache the list for one hour and provide a Refresh button. No personal TMDB token or “TMDB setup” screen is needed. The feed provides one digital release date per movie; do not claim it is specific to the person’s region. If Radarr’s service is unavailable or an image is missing, keep search and playback usable and show a fallback or readable error. Include TMDB’s required logo and attribution notice in the app Credits section because the service provides TMDB data and images.
• Search a poster title: A poster card’s Search this title button fills the search field and submits that title to the currently selected public torrent sources. Loading posters sends no personal query. Do not auto-play or fetch torrent data from the poster shelf.
• Play a result: Provide a separate Play action. On click, resolve the result’s magnet if needed, connect to that torrent, and show a video player with native controls. Do not start a torrent or fetch video pieces merely from searching or displaying results.
• Supported video: Choose the largest non-sample MP4, M4V, WebM, or MOV file. If none exists, show a clear message that the torrent has no browser-playable video. Do not transcode.
• Streaming and seeking: Fetch pieces sequentially for quick startup and prioritize pieces requested by the video player, including seeks. Serve the selected file through a random-port HTTP server bound only to 127.0.0.1, with correct byte-range responses. Stop the active torrent when the person closes the player; retain downloaded pieces so replay can resume.
• Show playback status: Show the selected file, downloaded progress, download speed, connected peers, buffered time, and whether playback is waiting, playing, paused, or buffering. Explain when metadata or peers are unavailable and allow stopping playback.
• Keep network behavior clear: Explain that popular-film metadata comes from Radarr’s metadata service and poster images come from TMDB’s image CDN, search terms go to selected public torrent sources, and playback connects to peers and may upload pieces while active. Do not send the person’s search terms to the metadata service. Do not add another intermediary service, analytics, or search-history storage.
• Clear search feedback: Give each search provider a 12-second timeout. Show loading, empty, and error states; if only some sources respond, show their results and name the sources that timed out or failed. Keep the app usable when a provider is unavailable or returns malformed data.
• Mac finish: Use a polished macOS window, a custom app icon, keyboard-friendly controls, and light and dark appearance. Name the app Netflaix unless the person chooses another name.

Constraints

• Use Electron and torrent-search-api version 2.1.4 for search, plus WebTorrent 3.x for playback. The main process owns all torrent and network work. The renderer has no Node integration and communicates through a small preload bridge with context isolation and sandboxing enabled.
• The player stream server must listen on 127.0.0.1 only and use an unguessable per-playback path. Do not expose a LAN or public streaming server.
• Do not register Netflaix as the default magnet handler or accept arbitrary pasted URLs. The only additional discovery shelf is the Radarr popular list filtered to released digital dates as specified above; playback still starts only from a search result’s magnet.
• Select only the chosen video file for downloading. Keep pieces in the app’s user-data folder; tell the person where they are and how to delete them to free space. Stop network activity when playback is closed and keep the on-disk data so it can resume.
• Do not collect or store private-provider passwords, tokens, cookies, or credentials. Do not add providers or scrape sites outside the package’s public-provider list.
• Popular-film metadata comes from api.radarr.video through the main process, and poster images load from TMDB’s image CDN. Search terms go only to each selected torrent provider. No personal TMDB token is collected or stored. Playback connects to the torrent’s peers and may share pieces while active. Explain this in the app; do not log queries, keep search history, add analytics, or send data to any other service.
• Use the public Radarr metadata service for the popular shelf; cache responses for one hour and do not poll more frequently than the person’s explicit Refresh action or cache expiry. No separate proxy service, transcoding, or bundled standalone torrent client. Opening a magnet in an external app requires the person’s explicit click.
• Escape source-provided text before displaying it. Validate magnet links before copying, opening, or starting playback. Restrict external link handling to the app’s explicit Open action.
• Keep a visible reminder to use the app only for content the person is authorized to access. Do not describe search results as licensed, verified, or safe.

Build steps

1. Check for macOS 14 or newer, Apple silicon, Node.js 22 or newer, and npm. Ask the questions above; if the person is unavailable, use the defaults.
2. Create or update the Electron project, install torrent-search-api 2.1.4 and WebTorrent 3.x, and confirm the search package’s public providers load.
3. Keep API requests in the Electron main process. Add a validated provider list, per-provider 12-second timeout, result cap, and partial-failure handling.
4. Add result sorting, source details, magnet lookup, clipboard copy, and explicit open-in-torrent-app actions.
5. Fetch https://api.radarr.video/v1/list/tmdb/popular from the main process without a user-supplied key. Validate the response is an array, filter for valid DigitalRelease dates on or before today in UTC, preserve feed popularity order, validate poster and backdrop URLs against https://image.tmdb.org, and cache for one hour.
6. Add poster cards, a missing-image fallback, digital release dates, TMDB popularity scores, and an explicit Search this title button that submits to the selected torrent sources. Keep the query fixed and do not send user-entered terms to TMDB.
7. Add the click-to-play IPC flow. On Play, create/reuse one WebTorrent client, store its data under the app user-data folder, wait for metadata, choose a supported video, deselect other files, and stream selected-file byte ranges on loopback. Stop playback on Close while preserving cached pieces.
8. Add player status polling, clear errors, the network-use notice, safe text rendering, the streaming-style home layout, dark appearance, and the custom Netflaix icon.
9. Build the macOS .app bundle into release/, launch it, and complete the acceptance checks below. Do not install it into /Applications unless the person explicitly asks.

Acceptance checks

• Launching the app shows the Netflaix brand, dark streaming-style navigation, a featured film area, a query field, category menu, and selectable public providers. Private providers cannot be enabled; only the optional TMDB catalog token is accepted.
• Submitting an empty search does not make a network request and gives a clear prompt. Searching with selected sources passes the query, category, and result limit to the API.
• Results from multiple working sources appear together and sort by numeric seed count descending. Results with missing seed counts stay visible below counted results.
• A provider failure does not erase results from working providers. If all selected providers fail, show a readable error and let the person try again.
• A result with a magnet copies the exact link when Copy is clicked. Open calls the system link handler only after Open is clicked.
• Searching and displaying a result do not start a torrent. Clicking Play starts playback; when metadata arrives, the player selects one supported non-sample video file and streams it with native controls.
• The loopback stream returns 206 with correct Content-Range for valid byte ranges and 416 for invalid ranges. Seeking requests the corresponding torrent pieces without downloading all earlier content first.
• Unsupported formats, missing magnets, dead swarms, and missing metadata produce readable errors. Closing the player stops the active torrent, and replay can use previously downloaded pieces.
• Playback status includes file progress, speed, peers, buffered time, and player state. The app explains that active torrent playback may upload pieces.
• Search terms are not stored or logged. No content downloads begin from a search, result display, or app launch. A video download starts only after Play is clicked.
• The featured area uses the first film from the popular shelf and its backdrop when available.
• The horizontal popular shelf shows the movies in Radarr’s popular feed that have a valid digital release date on or before today, preserving the feed’s popularity order. Cards show the digital release date and poster when available. The feed’s date is not guaranteed to be specific to the person’s region.
• A poster with no thumbnail shows a fallback. If Radarr’s metadata service is unavailable, search and playback remain usable and a readable error is shown.
• Clicking Search this title fills and submits that title to selected torrent sources. The shelf itself does not resolve magnets, start torrents, or download video.
• The app explains that popular-film metadata comes through Radarr’s metadata service, poster images come from TMDB, selected providers receive search terms, and torrent peers may receive and share playback pieces. TMDB’s required attribution is present in Credits.
• Build and launch the finished macOS app from release/; verify the visible app name and icon.

Hand-off to the person

Tell them:

• Where the finished Netflaix.app is and how to open it.
• Search terms go directly to selected public sources. Search history is not saved.
• Copy keeps a magnet link on the clipboard; Open hands it to their existing torrent app. Play starts streaming the selected video’s torrent and may upload pieces while it is active. Netflaix does not start a video download until Play is clicked.
• Downloaded pieces stay in the app’s macOS user-data folder and can be deleted there to free space.
• Only search for or access content they are authorized to use.
• Which sources were selected by default and how to change them.
• The in-app player flow was adapted from the Torrent Video Player recipe. The popular shelf uses Radarr’s TMDB-backed metadata service and needs no personal TMDB token. The service provides one digital release date per film, which may not match the person’s region.