From 75598e3eff318ab9afa9a7d8a9d788030d24b329 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Sun, 8 Feb 2026 02:54:44 +0000 Subject: [PATCH] docs: update upload guides to match code behavior - Add "External Link" and "Magnet Link" upload methods. - Document advanced NIP-71 metadata fields (Content Warning, Duration, IMETA). - Clarify file type support and browser-based size limits. - Add troubleshooting for CORS and memory issues. - Provide examples for S3-compatible providers (MinIO, DigitalOcean). Co-authored-by: PR0M3TH3AN <53631862+PR0M3TH3AN@users.noreply.github.com> --- content/docs/guides/upload-content.md | 54 +++++++++++++++++++++------ 1 file changed, 42 insertions(+), 12 deletions(-) diff --git a/content/docs/guides/upload-content.md b/content/docs/guides/upload-content.md index 532c1ee1..a3cf5828 100644 --- a/content/docs/guides/upload-content.md +++ b/content/docs/guides/upload-content.md @@ -1,11 +1,14 @@ # How to Upload Content -bitvid is a decentralized platform, but for larger video files, we support **Cloudflare R2** and **S3-compatible** storage backends. This allows you to upload files directly from your browser to a high-performance storage bucket. +bitvid is a decentralized platform that supports multiple ways to share video content. For direct uploads, we support **Cloudflare R2** and **S3-compatible** storage backends (like MinIO, DigitalOcean Spaces, or AWS S3), allowing you to upload files directly from your browser to a high-performance storage bucket. -## Prerequisites +## Upload Methods -- A **Cloudflare Account** (free to create) or an **S3-compatible provider**. -- An activated **R2 Plan** (if using Cloudflare). +bitvid offers three ways to publish content: + +1. **Direct Upload:** Upload a video file from your device to your configured storage bucket (R2 or S3). The client handles the upload, generates a magnet link for WebTorrent, and publishes the metadata to Nostr. +2. **External Link:** Provide a direct URL to a video file hosted elsewhere (e.g., on a personal server or another CDN). This URL serves as the primary playback source. +3. **Magnet Link:** assist the network by providing a magnet link for an existing torrent. Note that magnet-only uploads require at least one active seeder to be playable. ## Supported Media & Limits @@ -19,13 +22,31 @@ Before you start, ensure your content meets the following requirements: - **Recommended:** Up to **2GB** per file. - **Why?** Browser-based uploads rely on your device's memory for hashing and chunk management. Files larger than 2GB may cause browser instability or crashes. -### Metadata +## Metadata & Options + +When publishing a video, you can configure the following: + +### Basic Info - **Title:** **Required**. - **Description:** Optional. -- **Thumbnail:** Optional. -- **Tags (Hashtags):** Optional but highly recommended for discoverability. Use the dedicated "Hashtags" section in the upload form. +- **Thumbnail:** Optional (URL or upload). +- **Tags (Hashtags):** Optional but highly recommended for discoverability. -## Step-by-Step Guide +### Audience & Engagement +- **Enable Comments:** Toggle to allow or disable comments on your video. +- **NSFW:** Mark content as "Not Safe For Work" (e.g., artistic nudity, sensitive topics). +- **For Kids:** Mark content as specifically made for children. + +### Advanced Options (NIP-71) +For power users and technical configurations: +- **Content Warning:** A text label for sensitive content (automatically set to "NSFW" if the NSFW toggle is on). +- **Duration:** Manually specify the video duration in seconds. +- **Summary:** A short summary separate from the full description. +- **IMETA (Video Variants):** Define alternative video sources, resolutions, or MIME types. +- **Web Seed (ws):** Manually provide a web seed URL for the torrent. +- **Torrent File (xs):** Manually provide a URL to a `.torrent` file. + +## Step-by-Step Guide: Direct Upload ### 1. Create a Bucket & Enable Public Access @@ -81,8 +102,8 @@ bitvid will attempt to configure CORS automatically for generic S3 providers if - **Bucket Name**: The exact name of your bucket. - **Public Access URL**: The R2.dev or custom domain URL from Step 1 (e.g., `https://pub-xxx.r2.dev`). - **S3 Compatible**: - - **Endpoint**: The S3 API endpoint (e.g., `https://s3.us-east-1.amazonaws.com`). - - **Region**: (e.g., `us-east-1` or `auto`). + - **Endpoint**: The S3 API endpoint (e.g., `https://s3.us-east-1.amazonaws.com` or `https://nyc3.digitaloceanspaces.com`). + - **Region**: (e.g., `us-east-1`, `nyc3`, or `auto`). - **Access Key ID & Secret Access Key**: From Step 3. - **Bucket Name**: The exact name of your bucket. - **Public Access URL**: The base URL for public file access (e.g., `https://my-bucket.s3.amazonaws.com` or a CDN URL). @@ -90,11 +111,20 @@ bitvid will attempt to configure CORS automatically for generic S3 providers if bitvid will verify your credentials by attempting to list or upload a test file. Once verified, return to the Upload Modal to start sharing! +## Troubleshooting + +### Common Issues + +- **CORS Errors:** If you see "Network Error" or "CORS" in the console during upload, verify your bucket's CORS policy matches the JSON above. Ensure `AllowedHeaders` includes `*` or `amz-sdk-*`. +- **Upload Fails Immediately:** Check your API credentials and ensure the bucket name is correct. +- **Browser Crashes / Slow Performance:** Large files (>2GB) can exhaust browser memory during the hashing process. Try using a smaller file or ensuring you have plenty of free RAM. +- **Playback Issues:** If the video uploads but doesn't play, ensure the "Public Access URL" is correct and publicly reachable. + ## Upload Lifecycle & Moderation ### How Uploads Work -1. **Direct Upload**: Your browser uploads the file directly to your storage bucket. No video data passes through a bitvid server. -2. **Client-Side Hashing**: Your browser calculates a cryptographic hash (info hash) of the file to enable WebTorrent support. +1. **Direct Upload:** Your browser uploads the file directly to your storage bucket. No video data passes through a bitvid server. +2. **Client-Side Hashing:** Your browser calculates a cryptographic hash (info hash) of the file to enable WebTorrent support. 3. **Publication**: The video metadata (title, URL, hash, tags) is signed by your Nostr key and published to relays. ### Moderation & Visibility