Skip to main content

Couchcast Support

Frequently Asked Questions

  • How do I install Couchcast?

    Download couchcast-<version>.xpi from the latest release on GitHub (link at the bottom of this page) and drag it into a Firefox window. Mozilla signed it. A Firefox Add-ons listing is in Mozilla's review; once it's up, installing from there keeps Couchcast up to date. You need desktop Firefox 142 or newer.

  • Which mode should I pick?

    With an Apple TV and a Mac, pick No ads, straight to Apple TV: no ads, but it needs the free helper app. For any other TV, pick YouTube app on the TV: nothing else to install, and the TV's YouTube app shows its usual ads unless you have YouTube Premium. You can switch any time on the settings page.

  • How do I cast a video?

    Hover a YouTube video and click the cast button in the player controls, next to the settings gear. Or click the Couchcast button in the Firefox toolbar, right-click a YouTube link and choose Cast to TV, or press Alt+Shift+Y (Option+Shift+Y on a Mac). The TV picks up where you are, at your speed, and the video pauses in Firefox.

  • Why does no-ads mode need a helper app?

    A browser extension can't speak AirPlay. The helper is a small open-source app on your Mac: Firefox hands it the video, it gets the video's stream from YouTube with yt-dlp, and plays it on the Apple TV with pyatv. It talks to Firefox through native messaging, which Firefox asks you to allow when you pick that mode.

  • How do I set up the helper?

    Install uv (docs.astral.sh/uv) and deno (deno.com), then run these in Terminal. Pairing shows a PIN on the Apple TV to type in.

    uv tool install "git+https://github.com/vanities/couchcast#subdirectory=helper"
couchcast-helper pair
couchcast-helper install
couchcast-helper status
  • Does the helper work on Windows or Linux?

    It's tested on macOS. On Linux it registers itself with Firefox too, but it hasn't been tried there yet. Windows isn't supported. YouTube-app mode doesn't use the helper, so it works wherever desktop Firefox does.

  • How do I link a TV for YouTube-app mode?

    On the TV, open YouTube, then Settings > Link with TV code, and type the code it shows into Couchcast's settings page. Couchcast can't turn the TV on or open the YouTube app, so open YouTube on the TV before you cast.

  • The helper says YouTube wants me to confirm I'm not a bot.

    YouTube sometimes stops handing videos to apps on a network it finds suspicious, and that blocks the helper. The settings page has an option to let the helper ask once more with your YouTube login from Firefox. It's off by default, because YouTube can flag accounts used this way.

  • Why does my Mac have to stay awake?

    In no-ads mode your Mac sends the video to the Apple TV over AirPlay, and AirPlay video stops when the sender goes away. The helper keeps your Mac from idling to sleep while a video plays, but closing a laptop's lid still ends it.

  • Does it work on Firefox for Android, or with sites besides YouTube?

    Not today. Couchcast is for desktop Firefox, and it casts YouTube only.

  • Something went wrong. Where are the logs?

    The helper writes ~/.config/couchcast/helper.log, readable only by you. The extension's log is in Firefox: open about:debugging, choose This Firefox, and click Inspect next to Couchcast. Attach what's relevant when you open an issue.

  • Does Couchcast collect any data?

    No. It has no analytics and no server of its own; it talks to YouTube, your TV and the helper on your computer only to do what you ask. The privacy policy has the details.

Download and contact