Documentation

🚀 Quick Start

The easiest way to get started is to use the URL Generator on the homepage. It provides a simple user interface for configuring all the available options and generates a shareable URL for you.

Visit the homepage.
Select a platform (Twitch or Kick).
Enter a channel name.
Adjust the URL parameters as needed.
Click "🚀 Launch Player" to start the player or "📋 Copy URL" to share it.

🔧 URL Parameters

The player is configured via URL parameters. The platform is selected via the URL path (e.g., /player/twitch, /player/kick or /player/youtube).

Parameter	Type	Default	Description
`channelName`	string	required	The channel name for the selected platform.
`days`	number	`900`	Filter clips from the last N days.
`views`	number	`0`	Minimum view count for clips (0 = no filter).
`shuffle`	string	`smart`	Shuffle strategy: `smart`, `stratified`, `weighted`, `random`.
`volume`	number	`0.5`	Initial video volume (0.0 to 1.0).
`showLogo`	boolean	`true`	Show the channel's logo.
`showInfo`	boolean	`true`	Show clip information (title, creator, views).
`showTimer`	boolean	`true`	Show the countdown timer for the current clip.
`showProgressBar`	boolean	`true`	Show the progress bar.
`transparentBackground`	boolean	`false`	Make the background transparent.

🏗️ API Architecture

This application uses a proxy pattern to securely access platform APIs while avoiding CORS issues and protecting API credentials.

Twitch API

ClipsCards__User: Uses Twitch's persisted query for fetching clips with multiple time filters (LAST_DAY, LAST_WEEK, LAST_MONTH, ALL_TIME)
Multi-criteria fetching: Fetches 3-4 different time periods simultaneously for better clip diversity
Smart pagination: Continues with primary filter in background loading

Kick API

Cloudflare Worker Proxy: Bypasses Cloudflare bot detection by routing requests through Cloudflare Workers
HLS Manifest Patching: Patches Kick's HLS playlists to use absolute URLs for playback

❤️ Health Check

The application provides a health check endpoint at /api/health. This endpoint monitors the status of platform APIs and services.

Response Fields:

status: Overall status - ok or service_unavailable
platforms: Status of Twitch and Kick APIs (up/down)
services.kickProxyWorker: Cloudflare Worker status (up/down/not_configured)
timestamp: ISO 8601 timestamp

Example Response

{
  "status": "ok",
  "platforms": {
    "twitch": "up",
    "kick": "up"
  },
  "services": {
    "kickProxyWorker": {
      "status": "up"
    }
  },
  "timestamp": "2025-01-21T10:00:00.000Z",
  "_links": {
    "self": "https://clips.example.com/api/health",
    "docs": "https://clips.example.com/docs"
  }
}

🔌 API Endpoints

GET /api/twitch/clips

Fetch Twitch clips using ClipsCards__User operation

Query Parameters:

channelName (required): Twitch channel name
cursor (optional): Pagination cursor
filter (optional): LAST_DAY | LAST_WEEK | LAST_MONTH | ALL_TIME
days (optional): Auto-determine filter from days

Example Response:

{
  "edges": [
    {
      "cursor": "eyJpZCI6IjEyMzQ1Njc4OTAifQ==",
      "node": {
        "id": "1234567890",
        "slug": "ClipSlugHere",
        "title": "Amazing Play!",
        "viewCount": 15420,
        "createdAt": "2025-01-20T10:30:00Z",
        "durationSeconds": 30,
        "thumbnailURL": "https://clips-media-assets2.twitch.tv/...",
        "broadcaster": {
          "displayName": "ChannelName",
          "login": "channelname"
        },
        "curator": {
          "displayName": "ClipCreator",
          "login": "clipcreator"
        }
      }
    }
  ],
  "pageInfo": {
    "hasNextPage": true,
    "hasPreviousPage": false,
    "endCursor": "eyJpZCI6IjEyMzQ1Njc4OTAifQ=="
  }
}

GET /api/twitch/playback

Get authenticated playback URL for a Twitch clip

Query Parameters:

slug (required): Twitch clip slug

Example Response:

{
  "url": "https://production.assets.clips.twitchcdn.net/AT-cm%7C123456.mp4?sig=abc123...&token=eyJhbG..."
}

GET /api/kick/clips

Fetch Kick clips (via Cloudflare Worker proxy if configured)

Query Parameters:

channelName (required): Kick channel name
cursor (optional): Pagination cursor

Example Response:

{
  "clips": [
    {
      "id": "clip_abc123-def456-ghi789",
      "clip_url": "https://clips.kick.com/clips/...",
      "thumbnail_url": "https://clips.kick.com/clips/...",
      "title": "Epic Moment",
      "view_count": 8532,
      "liked": false,
      "likes": 145,
      "duration": 45,
      "created_at": "2025-01-20T15:45:30.000000Z",
      "video_url": "https://clips.kick.com/clips/.../abc123.m3u8",
      "creator": {
        "username": "viewer123",
        "profile_pic": "https://files.kick.com/images/user/..."
      },
      "channel": {
        "username": "channelname",
        "slug": "channelname"
      }
    }
  ],
  "cursor": "next_page_cursor_here"
}

GET /api/kick/manifest

Patch Kick HLS manifest for playback

Query Parameters:

url (required): Kick HLS manifest URL (encoded)

Example Response:

#EXTM3U
#EXT-X-VERSION:3
#EXT-X-TARGETDURATION:10
#EXT-X-MEDIA-SEQUENCE:0
#EXTINF:10.0,
https://stream.kick.com/video/path/segment0.ts
#EXTINF:10.0,
https://stream.kick.com/video/path/segment1.ts
#EXTINF:8.5,
https://stream.kick.com/video/path/segment2.ts
#EXT-X-ENDLIST

Content-Type: application/vnd.apple.mpegurl