90 lines
6.1 KiB
Markdown
90 lines
6.1 KiB
Markdown
# Terebi
|
|
|
|
A native macOS player for local media, YouTube videos and Miruro episodes, with a local-file queue, saved playback positions, compact mode and Chromecast support.
|
|
|
|
## Build and install
|
|
|
|
Requires macOS 15+, Xcode Command Line Tools with Swift 6, Python 3.9+ and Homebrew build tools. Build natively on Apple Silicon or Intel; Rosetta and cross-architecture builds are not supported.
|
|
|
|
```sh
|
|
brew install pkg-config meson ninja
|
|
# Intel Macs also need: brew install nasm
|
|
make install
|
|
export PATH="$HOME/.local/bin:$PATH"
|
|
```
|
|
|
|
Open **Terebi** from `~/Applications` or Spotlight. The CLI is installed at `~/.local/bin/terebi`; add that directory to your shell's `PATH` to keep it available.
|
|
|
|
The first build downloads dependencies. Quit Terebi before updating, then run `make install` again. To install elsewhere, use `make install APPDIR="/Applications"` (requires a writable directory) or set `PREFIX` to change the CLI prefix.
|
|
|
|
To run without installing, use `make run`. The built `.build/terebi.app` is self-contained; no separate FFmpeg, Python or yt-dlp installation is needed at runtime. Builds are ad-hoc signed, not notarized. Bundled licenses and source archives are in the app's Resources; public binary redistribution needs a separate license audit.
|
|
|
|
## Usage
|
|
|
|
- **Local files:** use **⌘O**, drag files onto the player, or choose Finder's **Open With**. Multiple files form a queue in natural filename order, with automatic advance. Use **View → Show Queue** to play, reorder or remove items; **+** or dropping files onto the sidebar appends them. The queue lasts only for the session; opening other media replaces it.
|
|
- **Streams:** use **Open Stream…** (**⇧⌘O**) or drop a supported link. YouTube supports individual videos, not playlists or channels. Miruro links must use `https://barelystarted.miruro.tv/watch/<opaque-id>/<slug>?ep=<episode>` with an explicit positive episode number; arbitrary streaming sites are not supported.
|
|
- **Seeking:** click or drag the progress track or thumb to seek. The thumb centers on the cursor, clamped to the track endpoints.
|
|
- **Miruro metadata:** titles and opening/ending intervals load independently of playback when available. Small rounded gaps mark interval boundaries in the slider. Inside a segment, **Skip Opening** or **Skip Ending** appears for up to ten seconds or until the segment ends; clicking seeks to its end. Ignored offers stay dismissed until the media is closed or replaced. Missing/invalid metadata leaves playback usable, and timings may differ between cuts. Nothing skips automatically.
|
|
- **Resume:** videos resume their saved position; finished videos restart from the beginning. Live and audio-only media do not save progress.
|
|
- **Compact mode:** press **P** for a floating player; double-click it to restore. Drag noninteractive areas to move the window. Use the titlebar pin to keep the normal window on top.
|
|
- **Quality:** YouTube defaults to SDR up to 1080p. Use **gear → Quality** for other available resolutions or automatic quality.
|
|
|
|
### Keyboard shortcuts
|
|
|
|
| Action | Default shortcut |
|
|
| --- | --- |
|
|
| Play / pause | Space or K |
|
|
| Seek backward / forward 5 seconds | ← / → |
|
|
| Seek backward / forward 10 seconds | J / L |
|
|
| Step one frame backward / forward | , / . |
|
|
| Volume down / up | ↓ / ↑ |
|
|
| Mute / unmute | M |
|
|
| Fullscreen | F or ⌃⌘F; Esc to leave |
|
|
| Compact mode | P or ⌃⌘P |
|
|
| Always on top | ⇧P |
|
|
| Close media | ⇧⌘W |
|
|
| Quit | Q or ⌘Q |
|
|
|
|
### Chromecast
|
|
|
|
Open media, select the **Cast** icon or **Playback → Cast to Device**, and choose a receiver on the same LAN. Allow macOS Local Network access and incoming firewall connections. Use **Find Cast Devices…** to retry discovery.
|
|
|
|
Playback controls and queue navigation work on the receiver. **Play on This Mac** returns to local playback at the receiver's position. Keep the Mac connected: it relays the media and prevents idle system sleep during playback, while allowing display sleep when casting. Closing the lid or explicitly sleeping the Mac can interrupt playback.
|
|
|
|
Cast output is limited to 1080p/30 fps; frame stepping and YouTube quality changes are local-only. Use Cast only on a trusted network. AirPlay is not supported.
|
|
|
|
## Command line
|
|
|
|
```sh
|
|
terebi "/path/to/video.mp4"
|
|
terebi 'https://youtu.be/jNQXAC9IVRw'
|
|
terebi --new-instance --no-config "/path/to/video.mp4"
|
|
terebi --help
|
|
```
|
|
|
|
The CLI opens one file or supported stream, reusing the running player by default. With no arguments, it opens or activates the player. `--new-instance` starts a separate player; `--no-config` uses built-in settings on a fresh launch. Put these options before the media argument. Before installation, use `.build/terebi` instead of `terebi`.
|
|
|
|
For native episode-URL playback, external resolved sources and progress reporting, see the [integration contract](docs/miruro-playback-handoff.md).
|
|
|
|
## Configuration
|
|
|
|
The optional config file is `~/.config/terebi/config.toml`, or `$XDG_CONFIG_HOME/terebi/config.toml` when `XDG_CONFIG_HOME` is absolute. To print all supported settings and key bindings:
|
|
|
|
```sh
|
|
terebi --default-config
|
|
```
|
|
|
|
Copy the settings you want to change into the config file; omitted settings keep their defaults. Settings load at startup, so restart the player after editing. Changes made through menus are session-only.
|
|
|
|
## Limitations
|
|
|
|
- SDR output only; HDR is not supported.
|
|
- No embedded or YouTube captions, manual audio-track selection, rotation or deinterlacing. External WebVTT subtitles are supported for resolved streams.
|
|
- Private, age-restricted, region-blocked or sign-in-required YouTube videos may fail; browser cookies are not used. Rebuild and reinstall for bundled YouTube extractor updates.
|
|
- Seeking can be slow on long-GOP or unindexed media. Live streams cannot be sought, and expired stream URLs are not automatically refreshed.
|
|
- Audio-device changes during playback are not handled.
|
|
|
|
## Development
|
|
|
|
Install FFmpeg for test fixtures (`brew install ffmpeg`), then run `make check`. The suite requires a graphical macOS session and a working audio device; it launches players and plays short test audio. See the [Makefile](Makefile) for individual check targets.
|