FetchStream is architected with a strict separation of concerns. Unlike conventional video downloaders that lock you into proprietary servers or commercial subscriptions, FetchStream separates the client browser extension from the execution backend.

Execution Modes: Local vs Server

Every detected media item gives you complete control over how to process it:

To build or host a compatible backend, your server must implement two straightforward REST endpoints: POST /api/server-relay and GET /api/server-status.

Content-Type: application/json
Authorization: Bearer <YOUR_API_KEY>
X-API-Key: <YOUR_API_KEY>

{
  "jobId": "job_1725900000000_abc12",
  "mediaUrl": "https://cdn.site.com/hls.m3u8",
  "fileName": "lecture_video.mp4",
  "type": "hls",
  "format": "mp4",
  "service": "gofile.io",
  "threads": 8,
  "headers": {
    "User-Agent": "Mozilla/5.0 ...",
    "Referer": "https://streaming-site.com/"
  },
  "credentials": {
    "caption": "My Optional Description",
    "gofile": {
      "token": "YOUR_GOFILE_API_TOKEN",
      "folderId": "OPTIONAL_FOLDER_ID"
    },
    "telegram": {
      "chatId": "-100123456789",
      "botToken": "1234:ABCDEF",
      "caption": "My Optional Description"
    },
    "s3_compatible": {
      "endpoint": "https://s3.us-east-1.amazonaws.com",
      "bucket": "my-bucket",
      "region": "us-east-1",
      "accessKeyId": "YOUR_KEY",
      "secretAccessKey": "YOUR_SECRET",
      "prefix": "optional/folder/path/"
    },
    "pixeldrain.com": {
      "apiKey": "YOUR_PIXELDRAIN_API_KEY"
    }
  },
  "useFallbackProxy": true
}

{
  "jobId": "job_1725900000000_abc12",
  "status": "QUEUED",
  "message": "Job received and queued successfully."
}

{
  "jobId": "job_1725900000000_abc12",
  "status": "RUNNING",
  "stage": "DOWNLOADING",
  "progress": 55.4,
  "speed": "12.8 MB/s",
  "completedSegments": 554,
  "totalSegments": 1000,
  "fileName": "lecture_video.mp4",
  "fileSize": 157286400
}

{
  "jobId": "job_1725900000000_abc12",
  "status": "COMPLETED",
  "stage": "COMPLETED",
  "progress": 100,
  "speed": "Complete",
  "fileName": "lecture_video.mp4",
  "fileSize": 284190120,
  "url": "https://gofile.io/d/abc123",
  "links": [
    {
      "service": "gofile.io",
      "name": "GoFile",
      "url": "https://gofile.io/d/abc123",
      "directUrl": "https://srv.gofile.io/download/web/abc123/video.mp4"
    }
  ]
}

{
  "jobId": "job_1725900000000_abc12",
  "status": "RUNNING",
  "stage": "UPLOADING",
  "progress": 82.5,
  "speed": "Telegram • 45.2/60.0MB (75%)",
  "fileName": "lecture_video.mp4"
}

{
  "jobId": "job_1725900000000_abc12"
}

{
  "ok": true,
  "jobId": "job_1725900000000_abc12",
  "status": "CANCELLED"
}

{
  "jobId": "job_1725900000000_abc12"
}

{
  "status": "healthy",
  "service": "FetchStream Remote Runner",
  "version": "1.0.0",
  "active_jobs": 0,
  "total_jobs": 12,
  "auth_enabled": true
}

Suitable for a Linux VPS, Raspberry Pi, home server, or local PC. The example includes FFmpeg and Python 3.11 for server-side stream processing.

📁 Reference Source Code & Dockerfile: server-examples/docker/

1. Launch with Docker Compose (1 Command)

git clone https://github.com/Abhishek-banal/fetchstream.git
cd fetchstream/server-examples/docker

docker compose up -d --build

2. Verify Server Health

curl http://localhost:8000/health

3. Connect to the Extension

1. Open the FetchStream extension and click the Settings (⚙️) icon.
2. In Remote Server / Cloud Runner URL, enter http://localhost:8000 (or your VPS domain, e.g. https://downloader.yourdomain.com).
3. Click outside the panel to save. Server Uploads will now run on your private server.

Do not own a server? You can run the cloud downloader using an Edge Worker or CI/CD pipeline with temporary runner VMs.

📁 Reference Blueprints & Workflows: server-examples/serverless/

1. Create Runner Repository: Create a private repository on your CI/CD provider and copy the blueprints from server-examples/serverless/ (workflows and functions) into your repository.
2. Enable Pipeline Permissions: In your private runner repository, ensure your CI/CD pipelines have read and write permissions to execute jobs.
3. Generate Provider Token: Generate a Personal Access Token or API Token in your CI/CD provider with pipeline execution scopes.
4. Deploy to an Edge Worker: Deploy the functions/api scripts to an Edge provider. For example, using Edge CDN Workers connected to your private runner repo:
   • Build output directory: public
   • Environment variables:
     • CI_TOKEN: Your copied CI/CD token
     • CI_REPO: your-username/your-runner-repo-name
5. Connect Extension: Copy your Edge Worker URL (e.g. https://my-fetchstream-runner.pages.dev) and paste it into the FetchStream extension settings under Remote Server URL.

Because FetchStream communicates via a standard JSON contract, you can implement a custom backend in any programming language using minimal code.

Minimal Python (FastAPI) Sample

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
import uuid

app = FastAPI()
app.add_middleware(CORSMiddleware, allow_origins=["*"], allow_methods=["*"], allow_headers=["*"])

jobs = {}

@app.post("/api/server-relay")
async def dispatch_task(data: dict):
    job_id = data.get("jobId") or str(uuid.uuid4())
    jobs[job_id] = {"status": "RUNNING", "progress": 0, "url": data.get("mediaUrl")}
    return {"jobId": job_id, "status": "QUEUED"}

@app.get("/api/server-status")
async def task_status(jobId: str):
    return jobs.get(jobId, {"status": "FAILED", "error": "Job not found"})

Supported Cloud Upload Targets

FetchStream includes upload adapters for several third-party storage hosts and generic object storage endpoints:

Provider Sizing & Capability Matrix

FetchStream supports direct client-side uploads to any S3-compliant object storage bucket (such as Edge Object Storage, S3-compatible Object Storage, Backblaze B2, or MinIO) using authentic Cloud Provider Signature Version 4 (SigV4) generated directly in your browser.

[
  {
    "AllowedOrigins": ["*"],
    "AllowedMethods": ["GET", "PUT", "HEAD"],
    "AllowedHeaders": ["*"],
    "ExposeHeaders": ["ETag"]
  }
]

Provider Parameter Specifications

FetchStream can upload downloaded streams, videos, and files directly to a private Telegram Channel, Group, or Chat using Telegram's official Bot API. Follow this step-by-step guide to create your bot and find your numeric Channel ID.

"forward_from_chat": {
  "id": -1001234567890,
  "title": "My Cloud Archive",
  "type": "channel"
}

FetchStream is an open-source, client-side utility and offloading bridge. Please review the following terms regarding third-party cloud hosting providers:

FetchStream is developed strictly as a developer utility, media stream analyzer, and personal archival tool. Please review the following principles: