{"id":24449252,"url":"https://github.com/pr0m3th3an/bitvid","last_synced_at":"2026-01-03T20:16:18.240Z","repository":{"id":273276968,"uuid":"912521300","full_name":"PR0M3TH3AN/bitvid","owner":"PR0M3TH3AN","description":"Nostr \u0026 WebTorrent Video Client","archived":false,"fork":false,"pushed_at":"2025-02-23T16:40:09.000Z","size":4655,"stargazers_count":7,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-07T06:06:28.653Z","etag":null,"topics":["bittorrent","ipfs","nostr","video","webtorrent"],"latest_commit_sha":null,"homepage":"https://bitvid.network","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PR0M3TH3AN.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2025-01-05T19:57:51.000Z","updated_at":"2025-03-22T01:35:39.000Z","dependencies_parsed_at":"2025-02-10T14:25:58.401Z","dependency_job_id":"a0629f4c-ac0a-4505-934d-e15feb0b71bf","html_url":"https://github.com/PR0M3TH3AN/bitvid","commit_stats":null,"previous_names":["pr0m3th3an/bitvid"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PR0M3TH3AN%2Fbitvid","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PR0M3TH3AN%2Fbitvid/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PR0M3TH3AN%2Fbitvid/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PR0M3TH3AN%2Fbitvid/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PR0M3TH3AN","download_url":"https://codeload.github.com/PR0M3TH3AN/bitvid/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252823918,"owners_count":21809713,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["bittorrent","ipfs","nostr","video","webtorrent"],"created_at":"2025-01-21T00:59:34.455Z","updated_at":"2026-01-03T20:16:18.233Z","avatar_url":"https://github.com/PR0M3TH3AN.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"![](https://bitvid.netlify.app/assets/jpg/bitvid.jpg)\n\n# bitvid - Decentralized Video Sharing\n\n##### IPNS: [k51qzi5uqu5dgwr4oejq9rk41aoe9zcupenby6iqecsk5byc7rx48uecd133a1](https://k51qzi5uqu5dgwr4oejq9rk41aoe9zcupenby6iqecsk5byc7rx48uecd133a1.ipns.dweb.link/)\n\n**bitvid** is a decentralized platform where users can share videos and follow creators with privacy and freedom. Built with a static site architecture, it’s lightweight, efficient, and fully decentralized, making it ideal for hosting or local deployment.\n\n---\n\n## Features\n\n- **Decentralized Sharing**: Publish and browse videos without a centralized server.\n- **Channel profile pages**: The [channel view](views/channel-profile.html) and `js/channelProfile.js` render banners, playlists, links, and follow stats so every creator has a branded landing page.\n- **Audience flags**: The [Upload](components/upload-modal.html) and [Edit Video](components/edit-video-modal.html) modals expose **NSFW** and **For Kids** toggles that map straight to note metadata for safer discovery.\n- **Richer metadata repeaters**: Configure variants, captions, segments, participants, references, and hashtags directly in the Upload modal so posts ship with structured context.\n- **Cloudflare R2 Uploads**: Publish through the modal’s Cloudflare flow with progress tracking and credential helpers.\n- **Encrypted Watch History**: Sync viewing activity privately through the NIP-04 encrypted pipeline with local fallbacks.\n- **Live View Counters**: Subscribe to view events and see totals update in real time on video cards and the video modal.\n- **Lightning Zaps**: Tip creators with Lightning payments via the Zap controls in the video modal.\n- **Private Video Listings**: Hide cards from shared grids by flipping the visibility switch in the Edit Video modal after publishing.\n- **Nostr Integration**: Use Nostr keys for login and interaction.\n- **WebTorrent Streaming**: Stream videos directly through torrent technology.\n- **Developer-Friendly**: Open source and customizable for your needs.\n- **Responsive Design**: Seamless experience across devices.\n\n---\n\n## For Users\n\n### Getting Started\n\n1. **Visit the Site**: Navigate to the live instance of **bitvid** (e.g., `[https://bitvid.network](https://bitvid.network)`).\n2. **Login with Nostr**:\n   - Use a compatible Nostr browser extension or manually input your public key.\n\n### Upload a video\n\nOpen the **Upload** modal from the header toolbar and start by selecting the NIP-71 event type that matches your post. The chooser sets the correct Nostr kind and schema defaults so the published note follows [`docs/nostr-event-schemas.md`](docs/nostr-event-schemas.md).\n\nBoth upload modes expose metadata repeaters for **variants**, **captions/text tracks**, **segments**, **hashtags**, **participants**, and **references**. Use these when you have multiple playback qualities (variants), accessibility tracks (captions), multipart drops (segments), discoverability tags (hashtags), credited collaborators (participants), or cross-posts/threads (references). Skip any repeater you don’t need—the base schema stays valid without them.\n\nPick the flow that matches your source material:\n\n- **Custom (hosted URL or magnet)**: Provide a title plus an HTTPS video URL and/or a WebTorrent magnet. The form requires at least one transport, validates `ws=`/`xs=` hints, keeps magnets raw by decoding them with `safeDecodeMagnet()` before publish, and applies whatever metadata repeaters you configured.\n- **Cloudflare (R2 direct upload)**: Enter your Cloudflare credentials in the guided form, optionally expand the **Advanced settings** accordion to override pathing or access controls, then drop media files for bitvid to upload through the R2 API. The modal tracks progress, applies your metadata selections, auto-fills the primary `imeta` variant once the upload completes, and publishes the resulting R2 URL back into the note automatically.\n\nHosted URLs remain the preferred playback path, and you can still add a magnet or supplemental web seeds when using either mode. Use the **Private** toggle to keep the resulting card visible only to you, and lean on the repeaters whenever you want to surface richer context or alternate assets as outlined in the event schema reference.\n\n### How playback works\n\n1. **URL-first**: `playVideoWithFallback({ url, magnet })` attempts the hosted URL immediately. Healthy URLs deliver the full experience without touching P2P resources.\n2. **WebTorrent fallback**: If the URL probe fails or returns an error status, bitvid falls back to WebTorrent using the raw magnet. The helpers append HTTPS `ws=`/`xs=` hints so peers seed quickly.\n3. **Safety checks**: Magnets are decoded with `safeDecodeMagnet()` and normalized via `normalizeAndAugmentMagnet()` before reaching WebTorrent. Trackers remain WSS-only to satisfy browser constraints.\n4. **Operator playbook**: If a deployment causes playback regressions, flip the relevant feature flags back to their default values in `js/constants.js` and redeploy. Capture the rollback steps in AGENTS.md and the PR description so the Main channel stays stable.\n\n### Watch history \u0026 view counts\n\n- **Encrypted watch history**: When you opt into watch history, bitvid stores entries locally and syncs them as NIP-04 encrypted events so only your keys can decrypt them. The History view and the Profile modal’s History tab hydrate from relays when available and gracefully fall back to the local cache when offline.\n- **Live view counters**: The `viewCounter` module hydrates totals from relays, subscribes to live updates, and dedupes local plays. Video cards and the video modal update in real time as new view events arrive.\n\n### Support creators with Lightning\n\nClick a card to open the video modal and use the **Zap** button (lightning bolt icon) to send Lightning payments. The Zap dialog walks you through selecting an amount, splitting sats, and pushing the payment through your active wallet connection or Nostr Wallet Connect session.\n\n### Moderation \u0026 safety controls\n\nOperators can tune thresholds and lists from the Profile modal:\n\n- The **Moderation** tab manages blur and autoplay limits plus the relay-synced mute/ban lists.\n- Each video card’s **More** menu surfaces per-video actions powered by `videoMenuRenderers.js`, including:\n  - **Repost** to boost the note as a kind 6 event.\n  - **Mirror** to republish the hosted URL and magnet as a kind 1063 event.\n  - **Rebroadcast** to push the existing event to additional relays (see cooldown note below).\n  - **Remove from history** to clear the item from your encrypted watch log.\n  - **Mute/Unmute creator** to control local visibility without severing follows.\n  - **Blacklist creator** for operators who maintain shared deny lists.\n  - **Block creator** to drop their events entirely.\n  - **Report** to issue a NIP-56 moderation report.\n- When a rebroadcast hits rate limits, the app surfaces cooldown guidance (e.g., “Rebroadcast is cooling down. Try again in 30s.”) so operators know when to retry without spamming relays.\n\n### Hashtag interests \u0026 disinterests\n\n- The Profile modal’s **Hashtags** tab lets you maintain interests (tags you want surfaced) and disinterests (tags to downrank) with dedicated input fields and per-tag remove actions. Preferences are cached locally so list edits render instantly.\n- bitvid persists the lists by publishing a replaceable `kind 30015` event (legacy `30005` remains readable) with the identifier `bitvid:tag-preferences`. The `HashtagPreferencesService` normalizes tags, keeps interests and disinterests mutually exclusive, and emits change events so UI stays in sync.【F:js/services/hashtagPreferencesService.js†L206-L276】【F:js/services/hashtagPreferencesService.js†L304-L324】【F:docs/nostr-event-schemas.md†L154-L201】\n- Legacy `30005` preference events are still fetched and decrypted; saving updates reissues them as `30015`, so convergence happens automatically as viewers adjust their lists. Operators who need a faster rollout can ask affected accounts to re-save (e.g., toggle a tag) to trigger the new publish cycle.【F:js/services/hashtagPreferencesService.js†L360-L470】【F:docs/nostr-event-schemas.md†L196-L201】\n- Preference payloads are encrypted before leaving the browser. The service attempts NIP-44 v2 first, falls back to NIP-44 or NIP-04 based on the signer/browser capabilities, records the active scheme in the `['encrypted', \u003cscheme\u003e]` tag, and decrypts in the same priority order when loading from relays.【F:js/services/hashtagPreferencesService.js†L520-L657】【F:js/services/hashtagPreferencesService.js†L356-L511】\n- Published ciphertext is stored on every configured write relay and accepted ones are tracked so operators can diagnose relay failures without exposing the plaintext list.【F:js/services/hashtagPreferencesService.js†L658-L711】\n\n---\n\n## For Developers\n\n### Local Setup\n\nTo run **bitvid** locally:\n\n1. Clone the repository:\n\n   ```bash\n   git clone https://github.com/PR0M3TH3AN/bitvid.git\n   cd bitvid\n   ```\n\n2. Start a local server:\n   - Using Python:\n     ```bash\n     python -m http.server 8000\n     ```\n   - Or with Node.js:\n     ```bash\n     npx serve\n     ```\n\n3. Open the site in your browser:\n\n```\nhttp://localhost:8000\n```\n\n### CSS build pipeline\n\nTailwind utilities are generated from `css/tailwind.source.css` and themed via\nthe shared tokens in `css/tokens.css`. Install dependencies once and lean on the\npackage scripts to keep formatting, linting, and generated output consistent:\n\n- **Token imports:** `css/tailwind.source.css` imports `css/tokens.css`, and\n  Tailwind consumes that source file directly so utilities inherit the same\n  palette, spacing, and typography primitives across the stack—no\n  `css/style.css` intermediary.\n- **Core scripts:**\n\n  ```bash\n  npm run format    # normalize CSS/HTML/JS/MD sources with Prettier + tailwindcss plugin\n  npm run lint:css  # enforce design token usage and guard against raw hex colors\n  npm run build     # run the Tailwind build locally (output remains gitignored)\n  ```\n\n- **No hard-coded colors:** Follow the token-first rules in `AGENTS.md`—reach\n  for semantic tokens instead of literal HEX/RGB values.\n- **Theme scopes:** Apply tokens by toggling the `data-theme` attribute on\n  scope wrappers so components stay palette-agnostic.\n\n```bash\nnpm install               # install Prettier, Stylelint, and Tailwind toolchain\nnpm run format            # format CSS/HTML/JS/MD with Prettier + tailwindcss plugin\nnpm run lint              # run CSS, hex color, inline-style, design-token, and Tailwind color/bracket guards in one pass\nnpm run lint:css          # enforce token usage and forbid raw hex colors\nnpm run lint:inline-styles # fail CI if inline style attributes or element.style usage slip in\nnpm run build             # run the Tailwind build (delegates to npm run build:css)\nnpm run build:beacon      # bundle torrent/dist assets and re-run the inline-style guard\nnpm run build:beacon:bundle # bundle beacon assets without running the guard (rarely needed)\n```\n\n#### Admin runbook: regenerate Tailwind styles\n\nNeed to confirm Tailwind picks up token or template changes? Run these\ncommands from the repo root:\n\n1. Install dependencies (only required after cloning or when packages change):\n\n   ```bash\n   npm install\n   ```\n\n2. Rebuild the Tailwind bundle for local verification (the output stays\n   gitignored and CI/Netlify handle deploy-time generation):\n\n   ```bash\n   npm run build:css\n   ```\n\nThe generated `css/tailwind.generated.css` artifact is ignored in git. CI\nworkflows and Netlify deploys run `npm run build` to produce the compiled\nstylesheet during deployment, so source changes are all you need to commit.\n\nInline styles are intentionally blocked. `npm run lint:inline-styles` scans HTML\nand scripts for `style=` attributes, `element.style`, or `style.cssText` usage\nand will fail CI until offending markup is moved into the shared CSS/token\nsystem.\n\n#### Design token guard\n\n`npm run lint:tokens` inspects JavaScript **and** `css/tailwind.source.css`\nfor raw `px`/`rem` measurements. Prefer design tokens, Tailwind `theme()` calls,\nor existing utilities over hard-coded lengths. When unavoidable (for example\nhairline borders or browser reset quirks) add an explicit allowlist entry in\n`scripts/check-design-tokens.mjs` so future contributors understand why the\nconstant exists.\n\nThe script now crawls every markup-emitting module under `js/ui`,\n`js/channelProfile.js`, and `torrent/ui`, so UI tweaks anywhere in the repo\nbenefit from the guard without manual configuration.\n\nBeacon builds inherit the same rule. `npm run build:beacon` now bundles\n`torrent/dist` and immediately re-runs the inline-style checker against the\nfresh output so third-party dependencies cannot sneak inline style mutations\ninto production. Use `npm run build:beacon:bundle` only if you need the raw\nesbuild output for debugging.\n\n### Nostr facade migration\n\nNostr helpers now ship behind dedicated facades so downstream plugins can pick\nthe entry point that matches their feature set:\n\n1. **Default client ([NIP-07](https://github.com/nostr-protocol/nips/blob/master/07.md)):** `import { nostrClient, requestDefaultExtensionPermissions } from './nostrClientFacade.js';`\n2. **View counters ([NIP-71](https://github.com/nostr-protocol/nips/blob/master/71.md)):** `import { recordVideoView, subscribeVideoViewEvents } from './nostrViewEventsFacade.js';`\n3. **Watch-history lists ([NIP-51](https://github.com/nostr-protocol/nips/blob/master/51.md) + [NIP-04](https://github.com/nostr-protocol/nips/blob/master/04.md) encryption):** `import { updateWatchHistoryListWithDefaultClient } from './nostrWatchHistoryFacade.js';`\n\n`js/nostr.js` remains as a compatibility shim while existing plugins migrate, but\nit will be removed in a future release. Move any legacy `import { ... } from './nostr.js';`\ncalls over to the facades above so upgrades stay painless.\n\nThe build command compiles Tailwind with `tailwind.config.cjs`, runs it through\nthe PostCSS pipeline defined in `postcss.config.cjs` (for autoprefixing), and\nemits the purged, minified stylesheet at `css/tailwind.generated.css`. That\nbundle is generated automatically during CI/Netlify deploys and remains\ngitignored locally; reference `css/tailwind.generated.css` in templates, but do\nnot commit the compiled file. Avoid vendoring legacy `tailwind.min.css`\nartifacts now that the deploy pipeline owns the build step.\n\n### Logo usage\n\n- Wrap inline logo `\u003csvg\u003e` elements with the `.bv-logo` component class. It\n  seeds `--logo-wordmark-color`, `--logo-accent-color`, and\n  `--logo-background-color` with the palette tokens exported in\n  `css/tokens.css`.\n- Adjust variants through data attributes instead of inline styles. For\n  example, `data-wordmark=\"current\"` ties the wordmark to the wrapper’s\n  `currentColor`, `[data-variant=\"inverse\"]` swaps in the inverse palette, and\n  `data-accent=\"current\"` makes the accent follow the surrounding text when\n  needed.\n- Inside the SVG, target elements with `.bv-logo__wordmark`,\n  `.bv-logo__accent`, and `.bv-logo__background` so fills inherit the custom\n  properties seeded by `.bv-logo`. Group paths with `\u003cg\u003e` wrappers where\n  possible to avoid repeating classes on every primitive.\n- Use Tailwind text utilities (such as `text-text-strong` or `text-text`) on the\n  wrapper to resolve to token-backed colors. Avoid hard-coded hex colors in the\n  SVG; customize the logo via the provided classes when deployments need a\n  different accent or background.\n\n### Configuration\n\n- **`config/instance-config.js`**:\n  - Central place for instance-specific values like the Super Admin npub and the\n    default whitelist-only mode setting. Update the documented exports here when\n    preparing a new deployment.\n  - Flip `IS_DEV_MODE` to `false` before shipping production builds. The flag\n    flows into `js/config.js` as `isDevMode`, seeds the\n    `window.__BITVID_DEV_MODE__` global for inline scripts, and gates whether the\n    dev logging channel emits to the console. See\n    [`docs/logging.md`](docs/logging.md) for rollout guidance.\n  - Tune `PLATFORM_FEE_PERCENT` (0–100) to keep a percentage of Lightning tips.\n    When the fee is positive, bitvid routes the platform’s split to\n    `PLATFORM_LUD16_OVERRIDE`, so set it to the Lightning address that should\n    receive the sats (or publish a `lud16` on the Super Admin profile). Leave\n    the fee at `0` to pass through every satoshi.\n  - Populate `DEFAULT_RELAY_URLS_OVERRIDE` with WSS URLs to replace the bundled\n    relay bootstrap list. Keep it empty to stick with the upstream defaults.\n  - Customize `THEME_ACCENT_OVERRIDES` with `#RRGGBB` hex strings when you want\n    light or dark mode to use different accent, accent-strong, or\n    accent-pressed colors. Leave the values `null` to inherit the defaults from\n    `css/tokens.css`.\n- **`js/config.js`**:\n  - Re-exports `isDevMode` (derived from `IS_DEV_MODE`) for modules, publishes\n    `window.__BITVID_DEV_MODE__`, and centralizes the global configuration\n    surface.\n- **`js/utils/logger.js`**:\n  - Provides the shared `logger` utility. Route user-facing errors through\n    `logger.user` and keep experimental diagnostics on `logger.dev` so operators\n    can quiet development noise in production. Details live in\n    [`docs/logging.md`](docs/logging.md).\n- **`js/constants.js`**:\n  - Source for browser-safe tracker lists and feature flags that govern WebTorrent behavior.\n- **Magnet helpers**:\n  - Use `safeDecodeMagnet()` and `normalizeAndAugmentMagnet()` from `js/magnetUtils.js` to preserve hashes and add `ws=` / `xs=` hints safely.\n\n### Relay compatibility\n\nbitvid now requests per-video discussion counts using the NIP-45 `COUNT` frame. The bundled client opens each relay via\n`this.pool.ensureRelay(url)` and streams a raw `COUNT` message, so your relay stack must understand that verb (nostr-tools ≥ 1.8\nor any relay advertising NIP-45 support). Relays that do not implement `COUNT` are skipped gracefully—the UI keeps the count\nplaceholder at “—” and development builds log a warning—so mixed deployments remain usable while you phase in compatible relays.\n\n### Adding Features\n\n1. **Fork the repository** and create a new branch for your feature.\n2. Make changes and test locally.\n3. Submit a pull request with a detailed explanation of your contribution.\n\n---\n\n## For Contributors\n\n### How to Contribute\n\n1. **Fork and Clone**:\n   ```bash\n   git clone https://github.com/PR0M3TH3AN/bitvid.git\n   cd bitvid\n   ```\n2. **Create a Branch**:\n   ```bash\n   git checkout -b feature/your-feature-name\n   ```\n3. **Make Changes**:\n   - Ensure your code follows best practices and is well-documented.\n4. **Test**:\n   - Validate the site functionality locally before submitting.\n5. **Submit a Pull Request**:\n   - Explain your changes and reference any related issues.\n\n### Contribution Guidelines\n\n- Follow the [GPL-3.0-or-later License](LICENSE).\n- Use clear, concise commit messages.\n- Respect the existing coding style and architecture.\n- Run the manual QA script (see below) and note results in PR descriptions for changes that affect upload or playback.\n\n---\n\n## Testing\n\nContinuous integration runs CSS linting/builds, the Playwright kitchen-sink snapshots, and the Node-based unit tests on every push.\nBefore pushing, run `npm run build` locally so the Tailwind bundle regenerates.\nPair that with `npm run test:unit` for application logic changes and\n`npm run test:visual` for presentation updates to mirror the CI surface area.\n\n### Manual QA checklist\n\nUse this checklist before releases or when altering upload/playback flows:\n\n1. Open the Upload modal, confirm validation (title plus URL or magnet), and test submissions for URL-only, magnet-only, and combined entries.\n2. Publish a post with both URL and magnet, verify the player streams the hosted URL, then simulate a URL failure and confirm WebTorrent playback.\n3. Paste encoded magnets to ensure `safeDecodeMagnet()` returns the raw string and `normalizeAndAugmentMagnet()` adds `ws=` / `xs=` hints without corruption.\n4. Confirm magnets include HTTPS `ws=` / optional `xs=` hints and use the WSS tracker list from `js/constants.js`.\n5. Spot-check Chromium and Firefox for console warnings (CORS, Range requests, tracker connectivity).\n\nSee [`docs/qa.md`](docs/qa.md) for the copy/paste-friendly checklist we share with QA.\n\n---\n\n## Acknowledgments\n\n**bitvid** leverages the following open-source technologies:\n\n- **Nostr Tools** for decentralized identity management.\n- **WebTorrent** for P2P video streaming.\n- **TailwindCSS** for responsive design.\n\n---\n\n## Contact \u0026 Support\n\n- **Website**: [bitvid.network](https://bitvid.network)\n- **GitHub**: [PR0M3TH3AN](https://github.com/PR0M3TH3AN)\n- **Nostr**: [npub13yarr7j6vjqjjkahd63dmr27curypehx45ucue286ac7sft27y0srnpmpe](https://primal.net/p/npub13yarr7j6vjqjjkahd63dmr27curypehx45ucue286ac7sft27y0srnpmpe)\n\n---\n\n## License\n\nGPL-3.0-or-later. See [LICENSE](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpr0m3th3an%2Fbitvid","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpr0m3th3an%2Fbitvid","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpr0m3th3an%2Fbitvid/lists"}