peertube-plugin-sponsorblock 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+GNU AFFERO GENERAL PUBLIC LICENSE
+Version 3, 19 November 2007
+
+Copyright (C) 2026 Jean-Baptiste L.
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as published
+by the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+---
+
+Full license text: https://www.gnu.org/licenses/agpl-3.0.txt

package/README.md

@@ -0,0 +1,161 @@
+# PeerTube Plugin SponsorBlock
+
+PeerTube plugin to integrate SponsorBlock and automatically skip (or permanently remove) sponsor segments from videos imported from YouTube.
+
+## Goal
+
+Allow PeerTube instances to leverage the crowdsourced SponsorBlock database to improve the viewing experience of videos imported from YouTube.
+
+## Project Status
+
+**Under active development**
+
+Phase 1 (client-side skip), Phase 2 (admin dashboard & periodic sync), and Phase 3 (permanent removal) are implemented.
+
+See the [User Guide](USER_GUIDE.md) for installation and usage instructions.
+
+## Features
+
+### Phase 1: MVP (Client-side skip)
+- Automatic YouTube ID detection on import
+- SponsorBlock segment retrieval via API
+- Automatic segment skipping in the video player
+- Local segment caching
+- Per-category configuration (sponsor, intro, outro, etc.)
+
+### Phase 2: Admin dashboard & sync
+- Admin dashboard with statistics and mappings table
+- Periodic sync with SponsorBlock (configurable interval)
+- Manual "Scan Imports" to map existing videos
+- Per-row Sync / Process / Delete actions
+- Color-coded category markers on the progress bar
+
+### Phase 3: Permanent removal
+- Background processing worker (30s polling)
+- Priority queue with retries
+- FFmpeg cutting (`-c copy`) and concatenation
+- Support for web-videos, HLS, and original files
+- API routes: single and bulk processing
+- Automatic processing on import (in `remove` mode)
+- Configurable `storage_path` setting
+
+## Architecture
+
+### Main components
+
+1. **YouTube-to-PeerTube mapping table**
+   ```sql
+   plugin_sponsorblock_mapping (peertube_uuid, youtube_id)
+   ```
+
+2. **SponsorBlock segments cache**
+   ```sql
+   plugin_sponsorblock_segments (youtube_id, start_time, end_time, category)
+   ```
+
+3. **FFmpeg processing queue**
+   ```sql
+   plugin_sponsorblock_processing_queue (video_uuid, segments, status, priority)
+   ```
+
+4. **Import hooks**
+   - Captures the YouTube ID on import
+   - Automatic segment retrieval
+   - Automatic queue insertion in `remove` mode
+
+5. **Processing worker**
+   - 30s polling (active only in `remove` mode)
+   - Optimistic locking (`FOR UPDATE SKIP LOCKED`)
+   - Automatic retry (3 attempts max)
+
+6. **Video player integration**
+   - Automatic segment skipping during playback
+   - Visual notifications
+
+7. **Admin dashboard**
+   - Stats cards (mapped videos, segments, time saved, queue pending)
+   - Mappings table with per-row actions
+   - Bulk actions (Scan Imports, Sync All, Process All)
+   - Periodic sync timer (configurable)
+
+## Documentation
+
+- [User Guide](USER_GUIDE.md) — Installation, configuration, and usage guide for instance administrators
+- [Development Guide](DEVELOPMENT.md) — Development setup, project structure, testing, and contributing
+- [Changelog](CHANGELOG.md) — Version history and release notes
+- [TODO](TODO.md) — Roadmap, planned features, and known issues
+- [Research](RESEARCH.md) — State-of-the-art research and PeerTube plugin capabilities
+- [Technical Analysis](TECHNICAL_ANALYSIS.md) — Technical analysis of permanent segment removal with FFmpeg
+
+## Research highlights
+
+### State of the art
+
+**No native SponsorBlock plugin for PeerTube currently exists.**
+
+Similar projects:
+- **peertube-plugin-chapters**: Manual chapters (not crowdsourced)
+- **Tubular**: Android app with SponsorBlock + PeerTube support
+
+Open feature requests since 2020:
+- [ajayyy/SponsorBlock#1209](https://github.com/ajayyy/SponsorBlock/issues/1209)
+- [ajayyy/SponsorBlock#1938](https://github.com/ajayyy/SponsorBlock/issues/1938)
+- [ajayyy/SponsorBlock#993](https://github.com/ajayyy/SponsorBlock/issues/993)
+
+### PeerTube capabilities
+
+The PeerTube plugin system supports:
+- Import hooks (`filter:api.video.post-import-url.accept.result`)
+- Video player hooks (`action:video-watch.video.loaded`)
+- Database access (custom table creation)
+- External HTTP requests (SponsorBlock API)
+- UI modification
+
+## Technologies
+
+- **PeerTube**: Decentralized video platform
+- **SponsorBlock API**: https://sponsor.ajay.app/api/
+- **FFmpeg/ffprobe**: For permanent segment removal
+- **PostgreSQL**: PeerTube database
+- **Node.js**: Plugin runtime
+
+## Resources
+
+### PeerTube documentation
+- [Plugin Guide](https://docs.joinpeertube.org/contribute/plugins)
+- [Plugin API](https://docs.joinpeertube.org/api/plugins)
+- [Architecture](https://docs.joinpeertube.org/contribute/architecture)
+
+### SponsorBlock
+- [API Documentation](https://wiki.sponsor.ajay.app/w/API_Docs)
+- [Source Code](https://github.com/ajayyy/SponsorBlock)
+
+## Contributing
+
+Contributions are welcome:
+- PeerTube experience and feedback
+- FFmpeg expertise
+- Testing on development PeerTube instances
+
+## License
+
+AGPL-3.0 (for compatibility with PeerTube)
+
+## Warnings
+
+### "Skip" mode (Phase 1)
+- Segments are still downloaded (no bandwidth savings)
+- Works only in the PeerTube web player
+
+### "Permanent removal" mode
+- Irreversible modification of video files
+- Uses `ffmpeg -c copy` (remuxing without re-encoding, fast and lossless)
+- Comment timestamps will be shifted after removal
+- Automatic retry (3 attempts) on error
+- **Recommended only with automatic backups**
+- Requires `ffmpeg` and `ffprobe` in the `PATH`
+
+---
+
+**Author**: Jean-Baptiste L.
+**Created**: 2026-01-31

package/assets/style.css

@@ -0,0 +1,409 @@
+/**
+ * PeerTube Plugin SponsorBlock
+ * Custom styles
+ */
+
+/* Segment markers on progress bar */
+.sponsorblock-marker {
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  background-color: rgba(0, 255, 0, 0.6);
+  pointer-events: none;
+  z-index: 30;
+  transition: background-color 0.2s ease;
+}
+
+.sponsorblock-marker:hover {
+  background-color: rgba(0, 255, 0, 0.8);
+}
+
+/* Sponsor category colors */
+.sponsorblock-marker[data-category="sponsor"] {
+  background-color: rgba(0, 255, 0, 0.6);
+}
+
+.sponsorblock-marker[data-category="selfpromo"] {
+  background-color: rgba(255, 255, 0, 0.6);
+}
+
+.sponsorblock-marker[data-category="interaction"] {
+  background-color: rgba(0, 191, 255, 0.6);
+}
+
+.sponsorblock-marker[data-category="intro"] {
+  background-color: rgba(0, 255, 255, 0.6);
+}
+
+.sponsorblock-marker[data-category="outro"] {
+  background-color: rgba(0, 32, 255, 0.6);
+}
+
+.sponsorblock-marker[data-category="preview"] {
+  background-color: rgba(255, 128, 0, 0.6);
+}
+
+.sponsorblock-marker[data-category="music_offtopic"] {
+  background-color: rgba(255, 0, 255, 0.6);
+}
+
+.sponsorblock-marker[data-category="filler"] {
+  background-color: rgba(127, 0, 255, 0.6);
+}
+
+/* Skip notification styling */
+.sponsorblock-notification {
+  position: fixed;
+  bottom: 80px;
+  right: 20px;
+  background-color: rgba(0, 0, 0, 0.8);
+  color: white;
+  padding: 10px 20px;
+  border-radius: 5px;
+  font-size: 14px;
+  z-index: 9999;
+  animation: fadeInOut 3s ease-in-out;
+}
+
+@keyframes fadeInOut {
+  0% {
+    opacity: 0;
+    transform: translateY(10px);
+  }
+  10% {
+    opacity: 1;
+    transform: translateY(0);
+  }
+  90% {
+    opacity: 1;
+    transform: translateY(0);
+  }
+  100% {
+    opacity: 0;
+    transform: translateY(-10px);
+  }
+}
+
+/* SponsorBlock mapping widget */
+.sponsorblock-widget {
+  margin-top: 10px;
+  font-size: 13px;
+}
+
+.sponsorblock-widget-toggle {
+  cursor: pointer;
+  color: #999;
+  user-select: none;
+  display: inline-block;
+  font-weight: 600;
+}
+
+.sponsorblock-widget-toggle:hover {
+  color: #ccc;
+}
+
+.sponsorblock-widget-form {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  margin-top: 6px;
+}
+
+.sponsorblock-widget-input {
+  font-family: monospace;
+  font-size: 13px;
+  padding: 4px 8px;
+  border: 1px solid #555;
+  border-radius: 4px;
+  background: #1a1a1a;
+  color: #eee;
+  width: 280px;
+}
+
+.sponsorblock-widget-input:focus {
+  outline: none;
+  border-color: #00b300;
+}
+
+.sponsorblock-widget-btn {
+  padding: 4px 14px;
+  border: none;
+  border-radius: 4px;
+  background: #00b300;
+  color: #fff;
+  font-size: 13px;
+  font-weight: 600;
+  cursor: pointer;
+}
+
+.sponsorblock-widget-btn:hover {
+  background: #009a00;
+}
+
+.sponsorblock-widget-btn:disabled {
+  background: #555;
+  cursor: not-allowed;
+}
+
+.sponsorblock-widget-status {
+  margin-top: 4px;
+  font-size: 12px;
+}
+
+.sponsorblock-widget-status.success {
+  color: #00b300;
+}
+
+.sponsorblock-widget-status.error {
+  color: #e74c3c;
+}
+
+.sponsorblock-widget-current {
+  margin-top: 6px;
+  color: #999;
+  font-size: 12px;
+}
+
+.sponsorblock-widget-current code {
+  background: #2a2a2a;
+  padding: 1px 5px;
+  border-radius: 3px;
+  font-family: monospace;
+  color: #ccc;
+}
+
+/* ==========================================
+   Admin Dashboard
+   ========================================== */
+
+.sponsorblock-admin-root {
+  padding: 20px 0;
+  font-size: 14px;
+  color: #eee;
+}
+
+/* Stats row */
+.sponsorblock-admin-stats {
+  display: flex;
+  gap: 16px;
+  flex-wrap: wrap;
+  margin-bottom: 24px;
+}
+
+.sponsorblock-admin-stat {
+  background: #1a1a1a;
+  border: 1px solid #333;
+  border-radius: 8px;
+  padding: 16px 20px;
+  min-width: 160px;
+  flex: 1;
+}
+
+.sponsorblock-admin-stat-value {
+  font-size: 28px;
+  font-weight: 700;
+  color: #00b300;
+  line-height: 1.2;
+}
+
+.sponsorblock-admin-stat-label {
+  font-size: 12px;
+  color: #999;
+  margin-top: 4px;
+  text-transform: uppercase;
+  letter-spacing: 0.5px;
+}
+
+/* Action buttons bar */
+.sponsorblock-admin-actions {
+  display: flex;
+  gap: 10px;
+  flex-wrap: wrap;
+  margin-bottom: 24px;
+}
+
+.sponsorblock-admin-btn {
+  padding: 8px 18px;
+  border: none;
+  border-radius: 4px;
+  font-size: 13px;
+  font-weight: 600;
+  cursor: pointer;
+  color: #fff;
+  background: #00b300;
+  transition: background 0.15s;
+}
+
+.sponsorblock-admin-btn:hover {
+  background: #009a00;
+}
+
+.sponsorblock-admin-btn:disabled {
+  background: #555;
+  cursor: not-allowed;
+}
+
+.sponsorblock-admin-btn--secondary {
+  background: #2a6dd4;
+}
+
+.sponsorblock-admin-btn--secondary:hover {
+  background: #1f5bb8;
+}
+
+.sponsorblock-admin-btn--danger {
+  background: #e74c3c;
+}
+
+.sponsorblock-admin-btn--danger:hover {
+  background: #c0392b;
+}
+
+/* Status message */
+.sponsorblock-admin-message {
+  margin-bottom: 16px;
+  padding: 10px 14px;
+  border-radius: 4px;
+  font-size: 13px;
+}
+
+.sponsorblock-admin-message--success {
+  background: rgba(0, 179, 0, 0.15);
+  color: #00b300;
+  border: 1px solid rgba(0, 179, 0, 0.3);
+}
+
+.sponsorblock-admin-message--error {
+  background: rgba(231, 76, 60, 0.15);
+  color: #e74c3c;
+  border: 1px solid rgba(231, 76, 60, 0.3);
+}
+
+/* Mappings table */
+.sponsorblock-admin-table-wrap {
+  overflow-x: auto;
+}
+
+.sponsorblock-admin-table {
+  width: 100%;
+  border-collapse: collapse;
+  font-size: 13px;
+}
+
+.sponsorblock-admin-table th {
+  text-align: left;
+  padding: 10px 12px;
+  border-bottom: 2px solid #333;
+  color: #999;
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: 0.5px;
+  white-space: nowrap;
+}
+
+.sponsorblock-admin-table td {
+  padding: 10px 12px;
+  border-bottom: 1px solid #222;
+  vertical-align: middle;
+}
+
+.sponsorblock-admin-table tr:hover td {
+  background: rgba(255, 255, 255, 0.03);
+}
+
+.sponsorblock-admin-table code {
+  background: #2a2a2a;
+  padding: 2px 6px;
+  border-radius: 3px;
+  font-family: monospace;
+  font-size: 12px;
+  color: #ccc;
+}
+
+/* Row action buttons */
+.sponsorblock-admin-row-actions {
+  display: flex;
+  gap: 6px;
+}
+
+.sponsorblock-admin-row-btn {
+  padding: 4px 10px;
+  border: none;
+  border-radius: 3px;
+  font-size: 11px;
+  font-weight: 600;
+  cursor: pointer;
+  color: #fff;
+  background: #444;
+  transition: background 0.15s;
+}
+
+.sponsorblock-admin-row-btn:hover {
+  background: #555;
+}
+
+.sponsorblock-admin-row-btn--sync {
+  background: #2a6dd4;
+}
+
+.sponsorblock-admin-row-btn--sync:hover {
+  background: #1f5bb8;
+}
+
+.sponsorblock-admin-row-btn--process {
+  background: #00b300;
+}
+
+.sponsorblock-admin-row-btn--process:hover {
+  background: #009a00;
+}
+
+.sponsorblock-admin-row-btn--delete {
+  background: #e74c3c;
+}
+
+.sponsorblock-admin-row-btn--delete:hover {
+  background: #c0392b;
+}
+
+.sponsorblock-admin-row-btn:disabled {
+  background: #555;
+  cursor: not-allowed;
+}
+
+/* Queue status badges */
+.sponsorblock-admin-badge {
+  display: inline-block;
+  padding: 2px 8px;
+  border-radius: 10px;
+  font-size: 11px;
+  font-weight: 600;
+}
+
+.sponsorblock-admin-badge--pending {
+  background: rgba(255, 193, 7, 0.2);
+  color: #ffc107;
+}
+
+.sponsorblock-admin-badge--processing {
+  background: rgba(42, 109, 212, 0.2);
+  color: #5b9aef;
+}
+
+.sponsorblock-admin-badge--done {
+  background: rgba(0, 179, 0, 0.2);
+  color: #00b300;
+}
+
+.sponsorblock-admin-badge--error {
+  background: rgba(231, 76, 60, 0.2);
+  color: #e74c3c;
+}
+
+/* Empty state */
+.sponsorblock-admin-empty {
+  text-align: center;
+  color: #666;
+  padding: 40px 20px;
+  font-size: 14px;
+}