bitvid - Decentralized Video Sharing

IPNS: k51qzi5uqu5dgwr4oejq9rk41aoe9zcupenby6iqecsk5byc7rx48uecd133a1

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.

---

Features

• Decentralized Sharing: Video sharing without central servers.
• Private Video Listings: Hide cards from shared grids so only the owner sees them.
• Nostr Integration: Use Nostr keys for login and interaction.
• WebTorrent Streaming: Stream videos directly through torrent technology.
• Developer-Friendly: Open source and customizable for your needs.
• Responsive Design: Seamless experience across devices.

---

For Users

Getting Started

1. Visit the Site: Navigate to the live instance of bitvid (e.g., [https://bitvid.network](https://bitvid.network)).
2. Login with Nostr:
   • Use a compatible Nostr browser extension or manually input your public key.

Post a video

The upload modal enforces Title + (URL or Magnet). Hosted URLs are strongly recommended so the player can start instantly, and you may also add a magnet for resilience.

• Title: Required. Matches the in-app validation copy.
• Hosted URL (recommended): Supply an HTTPS MP4/WebM/HLS/DASH asset. This is the primary playback path.
• Magnet (optional but encouraged): Paste the literal magnet:?xt=urn:btih:... string. The form decodes it with safeDecodeMagnet() to prevent hash corruption. Never wrap magnets in new URL()—store them raw or decode then pass directly to the helpers.
• Web seeds (ws=): HTTPS only. Point to a file root (e.g., https://cdn.example.com/video/). Mixed-content (http://) hints are rejected just like the modal message explains.
• Additional sources (xs=): Recommend adding an HTTPS .torrent link so WebTorrent peers can bootstrap faster.
• Trackers: Bitvid’s browser client only connects to WSS trackers shipped in js/constants.js. Do not add UDP or plaintext HTTP trackers to published magnets.
• Private toggle: Hides the card from shared grids so only you see it and adds a purple accent so the private state stands out.

How playback works

1. URL-first: playVideoWithFallback({ url, magnet }) attempts the hosted URL immediately. Healthy URLs deliver the full experience without touching P2P resources.
2. 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.
3. Safety checks: Magnets are decoded with safeDecodeMagnet() and normalized via normalizeAndAugmentMagnet() before reaching WebTorrent. Trackers remain WSS-only to satisfy browser constraints.
4. 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.

---

For Developers

Local Setup

To run bitvid locally:

1. Clone the repository:

   git clone https://github.com/PR0M3TH3AN/bitvid.git
   cd bitvid
   

2. Start a local server:

   • Using Python:

     python -m http.server 8000
     

   • Or with Node.js:

     npx serve
     

3. Open the site in your browser:

http://localhost:8000

CSS build pipeline

Tailwind utilities are generated from css/tailwind.source.css and themed via the shared tokens in css/tokens.css. Install dependencies once and lean on the package scripts to keep formatting, linting, and generated output consistent:

npm install          # install Prettier, Stylelint, and Tailwind toolchain
npm run format       # format CSS/HTML/JS/MD with Prettier + tailwindcss plugin
npm run lint:css     # enforce token usage and forbid raw hex colors
npm run build:css    # rebuild css/tailwind.generated.css from tailwind.source.css
npm run check:css    # CI-friendly guard that fails if tailwind.generated.css is dirty

The build command compiles Tailwind with tailwind.config.cjs, runs it through the PostCSS pipeline defined in postcss.config.cjs (for autoprefixing), and emits the purged, minified stylesheet at css/tailwind.generated.css. Commit the regenerated file alongside any template changes so deployments pick up the latest styles.

Configuration

• config/instance-config.js:
  • Central place for instance-specific values like the Super Admin npub and the default whitelist-only mode setting. Update the documented exports here when preparing a new deployment.
  • Tune PLATFORM_FEE_PERCENT (0–100) to keep a percentage of Lightning tips. When the fee is positive, BitVid routes the platform’s split to PLATFORM_LUD16_OVERRIDE, so set it to the Lightning address that should receive the sats (or publish a lud16 on the Super Admin profile). Leave the fee at 0 to pass through every satoshi.
  • Populate DEFAULT_RELAY_URLS_OVERRIDE with WSS URLs to replace the bundled relay bootstrap list. Keep it empty to stick with the upstream defaults.
• config.js:
  • Toggle isDevMode for development (true) or production (false).
• js/constants.js:
  • Source for browser-safe tracker lists and feature flags that govern WebTorrent behavior.
• Magnet helpers:
  • Use safeDecodeMagnet() and normalizeAndAugmentMagnet() from js/magnetUtils.js to preserve hashes and add ws= / xs= hints safely.

Relay compatibility

Bitvid now requests per-video discussion counts using the NIP-45 COUNT frame. The bundled client opens each relay via this.pool.ensureRelay(url) and streams a raw COUNT message, so your relay stack must understand that verb (nostr-tools ≥ 1.8 or any relay advertising NIP-45 support). Relays that do not implement COUNT are skipped gracefully—the UI keeps the count placeholder at “—” and development builds log a warning—so mixed deployments remain usable while you phase in compatible relays.

Adding Features

1. Fork the repository and create a new branch for your feature.
2. Make changes and test locally.
3. Submit a pull request with a detailed explanation of your contribution.

---

For Contributors

How to Contribute

1. Fork and Clone:

   git clone https://github.com/PR0M3TH3AN/bitvid.git
   cd bitvid
   

2. Create a Branch:

   git checkout -b feature/your-feature-name
   

3. Make Changes:
   • Ensure your code follows best practices and is well-documented.
4. Test:
   • Validate the site functionality locally before submitting.
5. Submit a Pull Request:
   • Explain your changes and reference any related issues.

Contribution Guidelines

• Follow the MIT License.
• Use clear, concise commit messages.
• Respect the existing coding style and architecture.
• Run the manual QA script (see below) and note results in PR descriptions for changes that affect upload or playback.

---

Testing

Use the manual QA checklist before releases or when altering upload/playback flows:

1. Open the Upload modal, confirm validation (title plus URL or magnet), and test submissions for URL-only, magnet-only, and combined entries.
2. Publish a post with both URL and magnet, verify the player streams the hosted URL, then simulate a URL failure and confirm WebTorrent playback.
3. Paste encoded magnets to ensure safeDecodeMagnet() returns the raw string and normalizeAndAugmentMagnet() adds ws= / xs= hints without corruption.
4. Confirm magnets include HTTPS ws= / optional xs= hints and use the WSS tracker list from js/constants.js.
5. Spot-check Chromium and Firefox for console warnings (CORS, Range requests, tracker connectivity).

See docs/qa.md for the copy/paste-friendly checklist we share with QA.

For automated DOM-focused regression coverage, run the Node-based test suite:

node tests/profile-modal-controller.test.mjs

---

Acknowledgments

bitvid leverages the following open-source technologies:

• Nostr Tools for decentralized identity management.
• WebTorrent for P2P video streaming.
• TailwindCSS for responsive design.

---

Contact & Support

• Website: bitvid.network
• GitHub: PR0M3TH3AN
• Nostr: npub13yarr7j6vjqjjkahd63dmr27curypehx45ucue286ac7sft27y0srnpmpe