mirror of
https://github.com/PR0M3TH3AN/bitvid.git
synced 2025-09-08 15:08:44 +00:00
created plan to add NIP-35 torrent support to bitvid
This commit is contained in:
Keep Creating Online
@@ -0,0 +1,205 @@
|
||||
# **bitvid: Enhanced NIP-35 + WebRTC Check Integration**
|
||||
|
||||
### Summary
|
||||
This NIP introduces **`kind=2003`** events as a standardized way to index BitTorrent metadata on Nostr. Such events typically include enough information for Nostr-based clients or indexers to display, categorize, and construct magnet links. They do **not** contain `.torrent` files themselves, only the metadata.
|
||||
|
||||
---
|
||||
|
||||
## 1. Torrent Events
|
||||
|
||||
**`kind=2003`** events are interpreted as “Torrent” posts. Clients can index, display, and search them. The essential tags are:
|
||||
|
||||
1. **`x`** (required)
|
||||
- The BitTorrent V1 info hash (hex-encoded).
|
||||
- Matches the `xt=urn:btih:HASH` parameter in magnet links.
|
||||
|
||||
2. **`file`** (optional, multiple)
|
||||
- Each `["file", "<filename>", "<filesize-in-bytes>"]` entry describes a file within the torrent.
|
||||
|
||||
3. **`tracker`** (recommended, multiple)
|
||||
- Each `["tracker", "<tracker-url>"]` entry specifies a tracker (UDP/HTTP/HTTPS/WSS).
|
||||
- If you want to support **WebTorrent/WebRTC** streaming, include at least one `wss://` tracker such as `wss://tracker.webtorrent.io`.
|
||||
|
||||
4. **`title`** (optional)
|
||||
- A short user-facing title or release name.
|
||||
|
||||
5. **`t`** (optional, multiple)
|
||||
- Simple categories or tags, e.g., `movie`, `tv`, `4k`, `3d`, `adult`.
|
||||
|
||||
### Example
|
||||
```jsonc
|
||||
{
|
||||
"kind": 2003,
|
||||
"content": "Extended cut with behind-the-scenes footage.",
|
||||
"tags": [
|
||||
["title", "The Outer Space (Extended Cut) 2025 UHD"],
|
||||
["x", "abc123def4567890abc123def4567890abc123de"],
|
||||
["file", "outer_space_2025_UHD.mkv", "78000000000"],
|
||||
["file", "extra_features", "2000000000"],
|
||||
["tracker", "udp://tracker.openbittorrent.com:6969/announce"],
|
||||
["tracker", "wss://tracker.webtorrent.io"], // WebRTC-compatible
|
||||
["t", "movie"],
|
||||
["t", "uhd"]
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Tag Prefixes for Extra Metadata
|
||||
|
||||
Beyond the basic torrent info, **NIP-35** supports optional tag prefixes to map the event to external data sources or richer category structures:
|
||||
|
||||
- **`tcat:`** A comma-separated category path (e.g., `["i", "tcat:video,movie,4k"]`).
|
||||
- **`newznab:`** [newznab](https://github.com/Prowlarr/Prowlarr/blob/develop/src/NzbDrone.Core/Indexers/NewznabStandardCategory.cs) category IDs.
|
||||
- **`tmdb:`, `ttvdb:`, `imdb:`, `mal:`, `anilist:`** References to well-known movie, TV, or anime databases.
|
||||
- May include specific media types, like `tmdb:movie:693134` or `mal:anime:9253`.
|
||||
|
||||
These references are optional but help indexers or other clients correlate torrent data with known database records.
|
||||
|
||||
### Example with prefixes
|
||||
```jsonc
|
||||
{
|
||||
"kind": 2003,
|
||||
"content": "Full UHD release with commentary track.",
|
||||
"tags": [
|
||||
["title", "Dune Part Two 2160p HDR"],
|
||||
["x", "abcdef0123456789..."],
|
||||
["file", "Dune.Part.Two.2024.UHD.mkv", "50000000000"],
|
||||
["tracker", "udp://tracker.openbittorrent.com:6969"],
|
||||
["tracker", "wss://tracker.webtorrent.io"],
|
||||
["i", "tcat:video,movie,4k"],
|
||||
["i", "tmdb:movie:693134"],
|
||||
["i", "ttvdb:movie:290272"],
|
||||
["t", "movie"],
|
||||
["t", "4k"]
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Constructing Magnet Links
|
||||
|
||||
A **kind=2003** torrent event provides data to build a magnet link, typically:
|
||||
|
||||
```
|
||||
magnet:?xt=urn:btih:<info-hash>&tr=<tracker1>&tr=<tracker2>...
|
||||
```
|
||||
|
||||
- **`x`** tag → `<info-hash>`
|
||||
- **`tracker`** tags → `&tr=<tracker-url>`
|
||||
|
||||
If a torrent is intended for **WebTorrent** streaming, it **must** have a `wss://` tracker in its `tracker` tags.
|
||||
|
||||
### Example Magnet
|
||||
```
|
||||
magnet:?xt=urn:btih:abc123def...&tr=wss%3A%2F%2Ftracker.webtorrent.io&tr=udp%3A%2F%2Ftracker.openbittorrent.com%3A6969
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. WebTorrent/WebRTC Considerations
|
||||
|
||||
1. **Include at least one `wss://` tracker** in your `tracker` tags. Example:
|
||||
```jsonc
|
||||
["tracker", "wss://tracker.webtorrent.io"]
|
||||
```
|
||||
2. **Active WebRTC seeder**: Even with a `wss://` tracker, the torrent must be seeded in real time by at least one WebTorrent/WebRTC peer. Without a WebRTC seed, browser-based clients (like Bitvid or other WebTorrent-powered apps) cannot download or stream.
|
||||
|
||||
3. **No `.torrent` file on Nostr**: This NIP is purely metadata (info hash, tracker URLs). Traditional BitTorrent clients can still use the magnet link if it has UDP/HTTP trackers.
|
||||
|
||||
---
|
||||
|
||||
## 5. Searching & Indexing
|
||||
|
||||
Implementers can:
|
||||
|
||||
- **Index** `kind=2003` events from multiple relays.
|
||||
- Provide an interface to **search** by:
|
||||
- Title (`["title", ...]`)
|
||||
- Info hash (`["x", ...]`)
|
||||
- File names (`["file", ...]`)
|
||||
- Categories (`["t", ...]`, `["i", "tcat:..."]`, etc.)
|
||||
- External references (`["i", "tmdb:movie:..."]`, `["i", "imdb:..."]`)
|
||||
- **Filter** adult content by a specific tag or category if desired.
|
||||
|
||||
---
|
||||
|
||||
## 6. Torrent Comments (kind=2004)
|
||||
|
||||
A **kind=2004** event is used to reply to a torrent event. It functions much like a regular text note (kind=1), but:
|
||||
- References the torrent event via NIP-10 reply tags.
|
||||
- Often used to discuss quality, seeding, or additional info about the torrent.
|
||||
|
||||
---
|
||||
|
||||
## 7. Blocklists & Adult Filtering
|
||||
|
||||
While the protocol is open, clients or aggregators may apply local policies:
|
||||
- **Blocklists** to ignore certain pubkeys or known spam.
|
||||
- **Adult filtering** to hide or show certain categories or tags (like `["t", "adult"]` or `["i", "tcat:video,adult"]`).
|
||||
|
||||
This is **not** enforced at the protocol level but is left to each implementer’s discretion.
|
||||
|
||||
---
|
||||
|
||||
## 8. Implementation Notes
|
||||
|
||||
1. **No `.torrent` Files**
|
||||
`.torrent` files are not stored on Nostr—just the info hash and any relevant tracker URLs.
|
||||
|
||||
2. **Announce Sets**
|
||||
Clients should collect **all** `["tracker", ...]` tags to build a comprehensive announce set in the magnet link. This ensures maximum connectivity for both UDP/HTTP and WebRTC trackers.
|
||||
|
||||
3. **Fallback**
|
||||
If a torrent lacks `wss://` trackers, WebTorrent clients can’t stream it unless an external service or user rehosts it with a WebRTC seed/tracker combination.
|
||||
|
||||
4. **Metadata Matching**
|
||||
If `["i", "tmdb:movie:693134"]` or similar tags are present, clients may fetch additional metadata (like cover art) from that external database. This is optional and outside the core scope of NIP-35 but encouraged for better user experience.
|
||||
|
||||
5. **Periodic Refresh**
|
||||
Since torrents are seeded in real time, a WebTorrent client (e.g., in a browser) may show a torrent as “active” only if at least one WebRTC seed is online. Clients/aggregators might periodically check the presence of active WebRTC peers to update their UI.
|
||||
|
||||
---
|
||||
|
||||
## 9. Example JSON
|
||||
|
||||
Below is a more complete JSON example following NIP-35 conventions, demonstrating various optional fields:
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"kind": 2003,
|
||||
"content": "Full UHD release. Contains behind-the-scenes extras, commentary track, and sample clips.",
|
||||
"tags": [
|
||||
["title", "Dune Part Two 2160p HDR"],
|
||||
["x", "abcdef0123456789abcdef0123456789abcdef01"],
|
||||
["file", "Dune.Part.Two.2024.UHD.mkv", "50000000000"],
|
||||
["file", "Behind.The.Scenes.mp4", "2000000000"],
|
||||
["tracker", "udp://tracker.openbittorrent.com:6969"],
|
||||
["tracker", "wss://tracker.webtorrent.io"],
|
||||
["tracker", "udp://tracker.coppersurfer.tk:6969"],
|
||||
["i", "tcat:video,movie,uhd"],
|
||||
["i", "tmdb:movie:693134"],
|
||||
["i", "imdb:tt15239678"],
|
||||
["t", "movie"],
|
||||
["t", "uhd"]
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. References & Links
|
||||
|
||||
- **[BitTorrent Magnet Link Specification (BEP-0053)](https://www.bittorrent.org/beps/bep_0053.html)**
|
||||
- **[WebTorrent Documentation](https://webtorrent.io/)**
|
||||
- **[NIP-10: Replies and Mentions](https://github.com/nostr-protocol/nips/blob/master/10.md)**
|
||||
- **[dtan.xyz Repository](https://git.v0l.io/Kieran/dtan)**
|
||||
- **[nostrudel.ninja Implementation](https://github.com/hzrd149/nostrudel/tree/next/src/views/torrents)**
|
||||
|
||||
---
|
||||
|
||||
### End of Updated Spec Sheet
|
||||
|
||||
This revision aims to integrate WebTorrent/WebRTC considerations seamlessly into the existing NIP-35 structure. It remains optional to provide `wss://` trackers, but doing so is strongly recommended if you want real-time streaming in browser-based clients like Bitvid or other WebTorrent-powered frontends.
|
||||
Reference in New Issue
Block a user