{"id":13616885,"url":"https://github.com/elonen/clapshot","last_synced_at":"2026-04-02T15:35:40.558Z","repository":{"id":95668336,"uuid":"538224630","full_name":"elonen/clapshot","owner":"elonen","description":"Self hosted web based collaborative video review tool","archived":false,"fork":false,"pushed_at":"2026-01-14T22:05:24.000Z","size":35912,"stargazers_count":198,"open_issues_count":12,"forks_count":17,"subscribers_count":10,"default_branch":"master","last_synced_at":"2026-01-15T04:31:20.032Z","etag":null,"topics":["annotation","annotation-tool","collaboration","linux-server","review","review-tools","video","webapp"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/elonen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-09-18T19:53:43.000Z","updated_at":"2026-01-15T02:14:15.000Z","dependencies_parsed_at":"2023-10-23T11:30:20.394Z","dependency_job_id":"f52ce0a9-b355-4841-81ac-5662536bfce0","html_url":"https://github.com/elonen/clapshot","commit_stats":null,"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"purl":"pkg:github/elonen/clapshot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elonen%2Fclapshot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elonen%2Fclapshot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elonen%2Fclapshot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elonen%2Fclapshot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/elonen","download_url":"https://codeload.github.com/elonen/clapshot/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elonen%2Fclapshot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29946894,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-28T18:21:26.597Z","status":"ssl_error","status_checked_at":"2026-02-28T18:19:38.892Z","response_time":90,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["annotation","annotation-tool","collaboration","linux-server","review","review-tools","video","webapp"],"created_at":"2024-08-01T20:01:34.417Z","updated_at":"2026-04-02T15:35:40.529Z","avatar_url":"https://github.com/elonen.png","language":"TypeScript","readme":"# Clapshot: Self-Hosted Video/Media Review Tool\n[![Release](https://img.shields.io/github/v/release/elonen/clapshot?include_prereleases)]() [![Build and test](https://github.com/elonen/clapshot/actions/workflows/docker-test.yml/badge.svg)](https://github.com/elonen/clapshot/actions/workflows/docker-test.yml)\n\n## Overview\n\nClapshot is an open-source, self-hosted tool for collaborative video/media review and annotation. It features a Rust-based API server and a Svelte-based web UI. This tool is ideal for scenarios requiring local hosting of videos due to:\n\n1. Policy constraints (*enterprise users*), or\n2. Cost-benefit concerns against paid cloud services (*very small businesses*)\n\n![Review UI screenshot](doc/video-commenting.webp)\n\n### Key Features\n\n- **Media Support**: Video, audio and image files with subtitle track management\n- **Media Ingestion**: HTTP uploads with progress tracking, or monitored folder processing (files assigned by OS ownership)\n- **Video Player**: Loop region control (i/o shortcuts), frame-by-frame navigation, comprehensive keyboard shortcuts\n- **Collaborative Review**: Real-time synchronized playback, drawing annotations with 7-color palette, threaded comments\n- **Professional Tools**: EDL import as time-coded comments, drawing undo/redo, timeline comment pins\n- **File Organization**: Hierarchical folder system with drag-and-drop, admin user management interface\n- **Media Processing**: FFmpeg transcoding with configurable quality, thumbnail generation\n- **Authentication**: Reverse proxy integration supporting OAuth, JWT, Kerberos, SAML, etc.\n- **Storage**: SQLite database with automatic migrations, file-based media storage\n- **Extensibility**: Plugin system for custom workflows and integrations\n\n*For a comprehensive feature list, see [FEATURES.md](FEATURES.md).*\n\n![Video listing screenshot](doc/video-list.webp)\n\n### When not to use Clapshot\n\nIf you don't require local hosting, or are not adept in networking and Linux, consider commercial cloud services which may offer more user-friendly interfaces and additional features out of the box.\n\n## Demo\n\n**Quick Start with Docker:**\n\n- Local **single-user demo:** No authentication\n\n```bash\ndocker run --rm -it -p 0.0.0.0:8080:80 -v clapshot-demo:/mnt/clapshot-data/data elonen/clapshot:latest-demo\n```\n\n- Local **multi-user demo** with HTTP basic auth:\n\n```bash\ndocker run --rm -it -p 0.0.0.0:8080:80 -v clapshot-demo-htadmin:/mnt/clapshot-data/data elonen/clapshot:latest-demo-htadmin\n```\n\nAfter the Docker image starts, access the web UI at `http://127.0.0.1:8080`.\n\n**Testing the demo:** Upload video/audio/image files via the web interface, or drop files into the container's `/mnt/clapshot-data/data/incoming/` directory for automatic processing. Try the keyboard shortcuts: spacebar (play/pause), 'i'/'o' (set loop points), 'l' (toggle loop), arrow keys (frame stepping).\n\nThe multi-user demo uses [PHP htadmin](https://github.com/soster/htadmin) for user management. Default credentials are shown in the terminal.\n\n\u003e **Note:** Chrome/Chromium works best. If accessing from a different machine, configure the `CLAPSHOT_SERVER__URL_BASE` environment variable (or legacy `CLAPSHOT_URL_BASE`). See the [Quick Start Reference](doc/quick-start-reference.md) for common deployment scenarios.\n\n\n### Known Limitations\n\n**Browser Compatibility:**\n- **Desktop-first design:** Chrome/Chromium recommended for best compatibility\n- **Mobile browsers:** Limited support - double-tap to open doesn't work on iOS/iPad, video player controls may not function properly, drawing annotations fail. Use desktop browsers for full functionality.\n\n**Reverse Proxy Considerations:**\n- **IIS:** Hard 2GB file upload limit (use monitored folder ingestion for larger files)\n- **Cloudflare free tier:** ~100 second upload timeout can interrupt large file uploads\n\nFor large file uploads with these proxies, use the [monitored folder ingestion](doc/sysadmin-guide.md#monitored-folder-ingestion) feature with SFTP/SMB instead of HTTP uploads.\n\n**Authentication:**\n- **PHP htadmin:** The included htadmin example is simplistic and limited for user management and security. For production deployments, consider integrating with a modern identity provider (OAuth, LDAP, Kerberos, SAML, etc.) via reverse proxy. See [Advanced Authentication](doc/sysadmin-guide.md#advanced-authentication).\n\n\n## Simple Small-business Production Deployments\n\nHere are two alternative ways to deploy Clapshot + PHP Htadmin into a light production use:\n\n### 1. Local Linux VM\n\nIf you have a virtualization platform (e.g. Proxmox) or a spare computer, here's\nhow to install and configure a Debian 12 host for Clapshot:\n\n1. Prepare a Debian 12 with a mounted block device (or just directory) at `/mnt/clapshot-data`.\n2. Download [Clapshot Debian Bookworm Deployment Script](https://gist.github.com/elonen/80a721f13bb4ec1378765270094ed5d5)\n3. Run the script as root to install and auto-configure Clapshot.\n4. **!! Change the default `admin` and `htadmin` passwords, and delete example users in Htadmin !!**\n\nIf you want to expose this to the Internet, you'll probably want to get HTTPS certificates with Let's Encrypt and use some reverse proxy to encrypt Clapshot traffic.\n\n\u003e **Security Note:** Monitored folder ingestion assigns files to users based on OS file ownership. Ensure file system permissions align with your intended user access model before enabling this feature.\n\n### 2. Docker + Cloudflare (make public on the Web)\n\nIn this option, you'll run Clapshot + Htadmin in a Docker container (binding a local directory for Clapshot data),\nand then start Cloudflared in another container to expose Clapshot to the Internet over an HTTPS tunnel.\n\n\u003e WARNING: Cloudflare – at least in the free plan – apparently limits HTTP upload times and/or sizes, so double check their offerings if you are planning to use this option for a production deployment.\n\n1. Download and read [test/run-cloudflare.sh](test/run-cloudflare.sh), then run it\n2. Once satisfied about operation, get a static domain on Cloudflare and modify the above script accordingly - or perhaps make a custom Docker Compose file\n3. **!! Change the default `admin` and `htadmin` passwords, and delete example users in Htadmin !!**\n\nThe same process can be adapted to any other *HTTPS-Proxy-as-a-Service* besides Cloudflare. You'll probably need to pay them something.\n\n## Configuration and Operation\n\n**New to Clapshot?** Start with the [Quick Start Reference](doc/quick-start-reference.md) for common deployment scenarios.\n\n**Need help?** Point your favorite LLM to [llms.txt](https://raw.githubusercontent.com/elonen/clapshot/refs/heads/master/llms.txt) for comprehensive configuration assistance. Most modern AI assistants (Claude, ChatGPT, Gemini, etc.) can read this file directly from the GitHub repository and help with installation, troubleshooting, and customization. Alternatively, you can try the [Clapshot Config Helper GPT](https://chatgpt.com/g/g-687debd7cfec8191ad14f604552f0121-clapshot-config-helper) (though it may have somewhat outdated documentation).\n\nSee the [Sysadmin Guide](doc/sysadmin-guide.md) for information on:\n\n- configuring Nginx reverse proxy (for HTTPS and auth)\n- using *systemd* for process management\n- performing database migrations\n- implementing advanced authentication methods\n- building manually and running unit tests\n\n\n**Having connection issues?** See the [Connection Troubleshooting Guide](doc/connection-troubleshooting.md) for help with common deployment and connectivity problems.\n\nSee [Upgrading Guide](doc/upgrading.md) for instructions on installing a new release over an old one.\n\n**Want to customize media processing?** See the [Transcoding and Thumbnailing Guide](doc/transcoding.md) for configuring hardware acceleration, custom encoders, and specialized processing workflows.\n\n\n## Architecture Overview\n\nMain components:\n\n- **Clapshot Client** – Single Page Application (SPA) that runs in the browser. Connects to Clapshot Server via Websocket. Written in *Svelte*.\n- **Clapshot Server** – Linux daemon that handles most server-side logic. Binary written in *Rust*. Listens on `localhost` to the reverse proxy for plaintext HTTP and WSS.\n- **Clapshot Organizer(s)** – Plugin(s) that organize media files into a custom folder hierarchy, etc. Written in Python (or any other language). See below for details.\n\nProduction deployments also depend on:\n\n- **Web Browser** – Chrome/Chromium recommended for best compatibility. Loads and shows the Client.\n- **Nginx Web Server** – SSL reverse proxy between Client and Server + static asset delivery for browser. Also routes session auth to Authentication Proxy.\n- **Authentication Proxy** – Any auxiliary HTTP daemon that authenticates users and returns a **user id** and **username** in HTTP headers. In the demo, this is `/var/www/.htpasswd` + [PHP htadmin](https://github.com/soster/htadmin), but you can also use combinations like [Okta](https://www.okta.com/) + [Vouch](https://github.com/vouch/vouch-proxy) + [LDAP Authz Proxy](https://github.com/elonen/ldap_authz_proxy) or something equally advanced.\n\n- **Sqlite DB** – Stores metadata, comments, user messages etc. Both Clapshot Server and Organizer(s) access this. This is just a file, not a daemon.\n- **ffmpeg** and **mediainfo** – Clapshot Server processes media files with these commands.\n- **File System** – Media files, HTML, JavaScript, CSS, thumbnail images etc, also `clapshot.sqlite`.\n\nSee [sequence diagram](doc/generated/open-frontpage-process.svg) for details on how these interact when a user opens the main page.\n\n## Organizer Plugin System\n\nClapshot includes an extensible [Organizer Plugin system](doc/organizer-plugins.md) that enables custom workflows and integrations. Organizers use gRPC communication and can be implemented in any language.\n\nThe included \"[basic_folders](organizer/basic_folders/README.md)\" organizer (Python) provides:\n- **Hierarchical Folders**: Personal folder structures for organizing media files\n- **Folder Sharing**: Token-based sharing of folder contents (still requires authentication to access)\n- **Admin Interface**: User management with batch operations and ownership transfer\n- **Metaplugin extensions**: Easier extension in Python:\n\n### Customization with Basic_Folders Metaplugins\n\n**NEW: Add custom functionality by dropping a single Python file into `/opt/clapshot-org-bf-metaplugins`** – no need to modify core code or deal with gRPC protocol directly. Example use cases:\n\n- **Add custom popup menu actions** to folders and media files (e.g., \"Auto-subtitle\", \"Export to archive\", \"Send to review\")\n- **Implement custom workflows** and business logic specific to your organization (e.g. video rename, ownership transfer, auto-folders)\n- **Integrate with external systems** (databases, LDAP, version controls, APIs) for authorization or processing\n- **Modify the UI dynamically** based on user roles, folder properties, or file metadata\n- **Run background process** such as automatic video expiration and trashing\n\nThis approach is **easier to develop** and **more robust against upgrades** than modifying core code or writing a full custom Organizer (if you're fine with Python). See [METAPLUGINS.md](organizer/basic_folders/METAPLUGINS.md) for complete documentation and a [working example](organizer/basic_folders/example_metaplugins/calculate_sha256.py).\n\n## Development Setup\n\nThe [development setup guide](doc/development-setup.md) covers setting up the server and client development environments, and running local builds and tests.\n\n## Contributions\n\nContributions are welcome, especially for features and improvements that benefit the wider user base. Please add your copyright notice for significant contributions.\n\n### Contributors\n\n  - **Client i18n, Chinese (Simplified) translations** – Mike-Solar\n\n## Licensing\n\nCopyright 2022 – 2026 by Jarno Elonen and contributors\n\n- Clapshot Server and Client are licensed under the **GNU General Public License, GPLv2**.\n- gRPC/proto3 libraries and example organizer plugins are under the **MIT License**.\n\nThis split licensing allows you to implement proprietary UIs and workflows through custom Organizer plugins without releasing them to the public.\n","funding_links":[],"categories":["HarmonyOS","Rust"],"sub_categories":["Windows Manager"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felonen%2Fclapshot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Felonen%2Fclapshot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felonen%2Fclapshot/lists"}