Merge pull request #2227 from PR0M3TH3AN/content-audit-upload-docs-15534095515326049500

🌐 Align /content user docs with actual upload & contribution behavior

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