# TV Cast

Browse your movie library on your Mac. Play locally or cast to a DLNA TV, with a web panel, CLI, resume, and queues.

Browse movies on your Mac and cast them to your TV. No TV app or video uploads.

Website: https://tvcast.thepushkarp.com
Repository: https://github.com/thepushkarp/tvcast

## Requirements

- macOS
- DLNA-compatible TV for casting
- Free & open source

## Features

### A library worth browsing.

Browse folders as collections. Search your movies, switch views, and add optional TMDB posters, cast, and ratings.

### Pick up where you left off.

Resume a cast, manage the queue, and adjust playback from the web panel or your terminal.

### Your Mac is the server.

No app to install on the TV. Video travels across your local network, without transcoding.

## From a folder to the sofa.

Add your movie folders in Settings. Play a file in your default Mac player, or find a TV on the same network and start casting.

### Open the library

Browse your collection and choose where to watch.

```text
tv ui
```

### Find your TV

Discover DLNA TVs on your local network.

```text
tv tvs --find
```

### Take control

Control a cast without leaving your terminal.

```text
tv pause
tv seek 1:05:00
tv volume 20
```

## Compatibility

Your TV must support the video and audio formats in the file. TV Cast sends the original file; it does not convert it.

| Capability | DLNA TVs | Samsung 2016+ |
| --- | --- | --- |
| Play, pause, seek, volume, resume | Supported | Supported |
| External subtitles | Depends on the TV | Switch while playing |
| Embedded subtitles | Depends on the TV | Use the TV menu |
| Remote buttons, typing, app launching | Unavailable | Supported |

## Installation

Requires macOS, Python 3.9+, uv, and Apple Command Line Tools.

### 1. Install and open

Starts the service at login and opens the web panel.

```text
uv tool install tvcast
tv install
tv ui
```

### 2. Add your movie folders

In Settings, add your movie folders. TMDB artwork and details are optional.

### 3. Choose your screen

Choose Find TVs in the TV tab and allow local-network access. Open a film and select Play on TV.

- [Install uv](https://docs.astral.sh/uv/getting-started/installation/)
- [Apple Command Line Tools](https://developer.apple.com/documentation/xcode/installing-the-command-line-tools/)

## Questions

### Do I need a Samsung TV?

No. Casting works with DLNA TVs. Samsung-specific features add remote buttons, text input, and app launching; the base playback controls work over DLNA.

### Can I use it without a TV?

Yes. Browse the library and open files in your default Mac player. Local playback does not update TV Cast’s TV resume point or interrupt an active cast.

### Does it upload my movies?

Video is served from your Mac to your TV over your network. If enabled, TMDB metadata lookups make requests to TMDB for movie information and artwork.

### How do I update or remove it?

Stop any active cast first. Run uv tool upgrade tvcast, then tv install to restart the service. To remove it, run tv uninstall before uv tool uninstall tvcast. Settings and playback history are retained.

### What if the TV cannot play a file?

TV Cast does not transcode. Install ffmpeg for optional runtime and compatibility checks, and use the troubleshooting guide for discovery, codecs, and subtitle issues.

## Documentation

- [Library guide](https://github.com/thepushkarp/tvcast/blob/main/docs/library.md)
- [Troubleshooting](https://github.com/thepushkarp/tvcast/blob/main/docs/troubleshooting.md)
- [Agent guide](https://tvcast.thepushkarp.com/agents.md)

## Interactive preview

The preview places the real TV Cast panel inside a Mac browser window. Open a film locally to launch a separate mock IINA player, or cast it to the paired Samsung TV. Local playback and TV playback have independent position and play/pause state. Both use poster artwork, without video or audio streaming. The browser never accesses real devices or local files. Reset clears the app, local player, and TV.

## App screenshots

Actual TV Cast UI with staged open-film data and licensed Blender Studio posters. Runtime values in the sample catalogue are illustrative.

- [Movie details](https://tvcast.thepushkarp.com/screenshots/details-light.png): Spring movie details in TV Cast, with Open in default player and Play on TV, synopsis, director, genres, and watched status.
- [Library](https://tvcast.thepushkarp.com/screenshots/library-light.png): TV Cast library with Spring, Charge, and Sprite Fright posters; search, genre, people and watched filters; local-playback and TV-casting controls.

## Artwork credits

- [Spring — Pillar poster](https://studio.blender.org/projects/spring/) by Blender Studio, [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). [Licensed source](https://studio.blender.org/projects/api/assets/909/?site_context=featured_artwork). Reproduced unchanged and scaled to fit.
- [Charge — official movie poster](https://studio.blender.org/projects/charge/) by Blender Studio, [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). [Licensed source](https://studio.blender.org/projects/api/assets/6234/?site_context=featured_artwork). Reproduced unchanged and scaled to fit.
- [Sprite Fright — simple poster](https://studio.blender.org/projects/sprite-fright/) by Blender Studio, [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). [Licensed source](https://studio.blender.org/projects/api/assets/5448/?site_context=featured_artwork). Reproduced unchanged and scaled to fit.