Metadata-Version: 2.4
Name: overc-clips
Version: 0.3.28
Summary: Cut volleyball analysis clips from video, locally or hosted. Web UI, no command line required.
Author-email: Bruce Ashfield <bruce.ashfield@gmail.com>
License-Expression: AGPL-3.0-only
Project-URL: Homepage, https://zedd.org/overc-clips/
Keywords: video,clips,volleyball,coaching,ffmpeg,yt-dlp
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Video :: Conversion
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: yt-dlp>=2024.1.1
Requires-Dist: imageio-ffmpeg>=0.5
Requires-Dist: pystray>=0.19; sys_platform != "linux"
Requires-Dist: pillow>=10; sys_platform != "linux"
Requires-Dist: pyobjc-framework-Cocoa>=10; sys_platform == "darwin"
Requires-Dist: pyobjc-framework-Quartz>=10; sys_platform == "darwin"
Dynamic: license-file

# overc-clips

Cut analysis clips out of a YouTube video or a local file, through a web page,
with no command line required.

Built for volleyball coaches handing clips to video-review sites, but there is
nothing sport-specific in it. Point it at a video, mark the spans you want, and
it produces the clips.

It runs two ways from one codebase:

- **On your own machine.** It starts a small web server and prints an address.
  Open that in a browser on the same machine, or on your phone if you are on the
  same wifi. The video processing happens on your computer; the phone is only
  the remote control.
- **Hosted**, like any other internal web app.

## What you need

**Python 3.10 or newer. That is all.** ffmpeg and yt-dlp come with it — the
install pulls a static ffmpeg build, so there is nothing to install separately
and nothing to put on your PATH.

Works on macOS, Linux and Windows.

## Install

```bash
pip install overc-clips
```

On current macOS and most Linux distributions that will refuse with a message
about an "externally managed environment" — that is the operating system
protecting its own Python, not an error in this package. Use a virtualenv:

```bash
python3 -m venv ~/.local/share/overc-clips/venv
~/.local/share/overc-clips/venv/bin/pip install overc-clips
~/.local/share/overc-clips/venv/bin/overc-clips serve
```

or install it with `pipx`, which does the same thing for you:

```bash
pipx install overc-clips
```

## Use it

```bash
overc-clips serve              # start the web UI, print the address to visit
overc-clips doctor             # what it found on this machine, and what is missing
```

`serve` prints a local address and, if it can, a second one for other devices on
your network. Everything else happens in the browser: paste a video link, scrub
to the start and end of each clip, and make them.

Useful flags:

```bash
overc-clips serve --outdir ~/Movies/clips   # where clips are written
overc-clips serve --port 8080               # default
overc-clips serve --token secret            # require a token, for a shared network
```

Settings you would otherwise need a flag for — the output folder, how long clips
are kept, the maximum clip length — are in the web UI itself, so someone who was
handed a desktop shortcut can still change them.

## Clips

Clips are named after the source video and their timestamps, so two cuts from
one match never collide. Where each clip came from is written into the file as
mp4 metadata, which survives the file being moved or shared, and the built-in
library can group, search and file them.

Clips are deleted after 14 days by default, which the UI tells you on startup
and lets you change or switch off.

## Keeping it working

YouTube changes things regularly and an out-of-date yt-dlp is the usual cause of
a download that suddenly fails. Updating it is independent of this package:

```bash
pip install -U yt-dlp        # in whichever environment you installed into
```

`overc-clips doctor` reports the version it is using and where it came from.

## Licence

GNU Affero General Public License, version 3. See `LICENSE`.

If you change it and pass it on, the changes come with it. The Affero part
extends that to running a modified copy as a service for other people over a
network — which for a web application is the case that matters. Improvements
sent back are welcome.

**This is early software and it changes often.** Treat it as alpha: things move,
and nothing here is supported.
