mirror of
https://github.com/PR0M3TH3AN/bitvid.git
synced 2026-10-27 16:02:26 +00:00
199 lines
8.7 KiB
Markdown
199 lines
8.7 KiB
Markdown
|
||
|
||
# bitvid - Decentralized Video Sharing
|
||
|
||
##### IPNS: [k51qzi5uqu5dgwr4oejq9rk41aoe9zcupenby6iqecsk5byc7rx48uecd133a1](https://k51qzi5uqu5dgwr4oejq9rk41aoe9zcupenby6iqecsk5byc7rx48uecd133a1.ipns.dweb.link/)
|
||
|
||
**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:
|
||
|
||
```bash
|
||
git clone https://github.com/PR0M3TH3AN/bitvid.git
|
||
cd bitvid
|
||
```
|
||
|
||
2. Start a local server:
|
||
- Using Python:
|
||
```bash
|
||
python -m http.server 8000
|
||
```
|
||
- Or with Node.js:
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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**:
|
||
```bash
|
||
git clone https://github.com/PR0M3TH3AN/bitvid.git
|
||
cd bitvid
|
||
```
|
||
2. **Create a Branch**:
|
||
```bash
|
||
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](https://opensource.org/licenses/MIT).
|
||
- 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`](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:
|
||
|
||
```bash
|
||
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](https://bitvid.network)
|
||
- **GitHub**: [PR0M3TH3AN](https://github.com/PR0M3TH3AN)
|
||
- **Nostr**: [npub13yarr7j6vjqjjkahd63dmr27curypehx45ucue286ac7sft27y0srnpmpe](https://primal.net/p/npub13yarr7j6vjqjjkahd63dmr27curypehx45ucue286ac7sft27y0srnpmpe)
|