ShhhPlay documentation

Requirements

ShhhPlay is a native Apple-platform player. Playback is AVFoundation and AVPlayer; the built-in browser is WKWebView. No libmpv, no FFmpeg and no third-party copyleft playback engine is linked into the app.

• macOS 15 or later, Apple silicon only. Intel Macs are not supported.
• iOS and iPadOS 18 or later.
• No account, no sign-in, no telemetry and no update ping.
• The macOS and iOS apps share one feature set. iOS is never a superset of macOS.

Installing

Two channels. The App Store build is sandboxed and updates itself. The direct DMG additionally bundles shhh-cli, which the App Store build cannot ship: a terminal tool that takes arbitrary file paths cannot be sandboxed.

The direct build is not notarised yet, so the first launch needs one extra step. Verify the checksum first — it is published next to the download link.

• Download the DMG, drag ShhhPlay to Applications, then eject the disk image.
• Verify what you downloaded: run shasum -a 256 ShhhPlay-macOS.dmg and compare it with the published SHA-256.
• First launch: macOS will refuse to open it. Go to System Settings → Privacy & Security, find the blocked ShhhPlay entry and choose Open Anyway. It launches normally from then on.
• Or remove the quarantine flag yourself: xattr -dr com.apple.quarantine /Applications/ShhhPlay.app

shasum -a 256 ShhhPlay-macOS.dmg
xattr -dr com.apple.quarantine /Applications/ShhhPlay.app

Playing something

Three ways in: a local file, a direct media URL, or a video handed off from the built-in browser. With history recording off — the default — none of them is recorded anywhere.

• Open File, or drag a file onto the window. On iPhone and iPad this reads through the Files app.
• Opening several files on Mac gives each its own window. There is no app-level playlist, so there is no queue that could reveal what you lined up.
• Open URL takes a direct media link — .mp4, .mov, .mkv, .m3u8 and anything else AVFoundation reads.
• Open Web browses in a neutral window with an ad and tracker content blocker, then hands a detected video to the player. The page's Referer, Origin and User-Agent travel with playback, which is what makes sources that check them work.
• Subtitles: local SRT and VTT files, plus automatic matching of subtitle files sitting next to the video. Audio and subtitle tracks are selectable from the control bar.
• The player window can be pinned above everything, including full-screen apps on other desktops. Drag anywhere in the window to move it, not just the title bar.

Saving a video you are streaming

While a network video plays, the control bar shows a Save button. Choose a folder, optionally tick Encrypt this download, and the file is written where you asked. Playback continues throughout, and cancelling removes the partial file.

The download sends the same request headers as playback, so a video handed off from the built-in browser saves even when the server checks Referer or User-Agent.

• Progressive sources — MP4, MOV, MKV, anything served as a single file — are saved as they are.
• HLS (.m3u8) is saved by fetching every segment and joining them into one file: MPEG-TS, or MP4 when the stream is fragmented MP4. AES-128 protected segments are decrypted on the way in.
• Ticking Encrypt this download asks for a password of at least 12 characters and writes a .shhh file. The video is encrypted as it downloads, so the plain video never touches the disk.
• The button does not appear for local files — those are already on disk, and the lock button encrypts them in place.
• Live streams are refused: a playlist that is still growing has no end to save. DASH (.mpd) is not supported. FairPlay and SAMPLE-AES streams are refused rather than half-saved.
• One download at a time per window, and downloads do not resume across launches — persisting a partial-file map would contradict the promise to leave nothing behind.

Password-protected video (.shhh)

A .shhh file is a video encrypted with a password you choose. ShhhPlay plays it directly: chunks are authenticated and decrypted in memory as playback streams, seeking included, and the unprotected video is never written back to disk.

There is no recovery. Forget the password and the file is gone — that is the design, not an oversight.

• Format: 1 MiB chunks sealed with ChaCha20-Poly1305, keys derived with PBKDF2-HMAC-SHA256 and HKDF, a fixed 128-byte header, and a separate authentication tag per chunk.
• A chunk reaches the player only once it authenticates, so a tampered file fails instead of playing corrupted video.
• Encrypt a local video from the lock button in the control bar, and restore it from the same button.
• Minimum password length is 12 characters, in the app and in the CLI alike.
• On iPhone and iPad you can save an encrypted download, but playing .shhh files back is macOS-only for now.

shhh-cli

The direct download bundles a command-line tool for the same format the app reads. Install it once from the app bundle, then use it anywhere.

It asks for the password on the terminal with no echo. Automation can pipe one in with --password-stdin; there is deliberately no plaintext --password flag, because that would leave the password in your shell history and in the process list.

/Applications/ShhhPlay.app/Contents/MacOS/shhh-cli --help

shhh-cli encrypt video.mp4        # → video.mp4.shhh
shhh-cli play video.mp4.shhh     # open in ShhhPlay
shhh-cli decrypt video.mp4.shhh  # → video.mp4

# automation
printf '%s' "$PASSWORD" | shhh-cli encrypt video.mp4 --password-stdin

Live captions

ShhhPlay can caption what is playing in real time, but it ships no speech model and no inference runtime. Recognition happens in a Caption Service you configure — your own endpoint, on your machine or anywhere you trust.

The player extracts short audio windows from the current playback position and sends them with nothing but the timing needed to place the result. The service never receives the media URL, cookies, Referer, Origin or any browser header.

• Any endpoint compatible with the OpenAI audio transcription API works, including a local one.
• Only HTTPS, or plain HTTP on loopback. Requests use an ephemeral session with cookies, caching and redirects disabled.
• Results that arrive after you seek are discarded rather than shown against the wrong moment.
• No model file ships in the app and none is downloaded. A clean checkout builds without one.

Local data

Playback history recording is off by default. While it is off, playback history, recent documents, resume points and the thumbnail cache are not written.

Turning it on is deliberate and reversible. Turning it back off clears what was recorded, and the Local Data window lets you erase each category by hand.

Known limits

Stated plainly, so none of it is a surprise after you install.

• DASH (.mpd) cannot be saved. HLS and progressive sources can.
• Live streams cannot be saved, because they have no end.
• Downloads do not resume after quitting the app.
• Playing .shhh files is macOS-only for now; iPhone and iPad can create them but not open them.
• Intel Macs are not supported.
• The direct DMG is not notarised yet, so the first launch needs the Open Anyway step described above.