Cat Catch

https://github.com/xifangczy/cat-catch
Admin
Cat Catch is a resource sniffing extension that helps you filter and list resources on the current...
Tokens:37,560
Snippets:469
Trust Score:9.2
License:GPL-3.0
Update:2 months ago
Show doc for...
Tokens:
Raw
### Usage examples for fileNameParse

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/api-reference/media-detection.md

Demonstrates how the function handles various URL path inputs.

```javascript
fileNameParse('/path/to/video.mp4')     // Returns ['video', 'mp4']
fileNameParse('/api/stream?v=123')      // Returns ['stream', '']
fileNameParse('/path/')                 // Returns ['', '']
```

--------------------------------

### Regex Pattern Examples

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/api-reference/media-detection.md

Examples of regex patterns for platform-specific APIs, blocking rules, and URL cleanup.

```javascript
// Platform-specific video API
{
  regex: /https:\/\/cache\.video\.[a-z]*\.com\/dash\?tvid=.*/,
  ext: 'json',
  state: false
}

// Block Bilibili live segments
{
  regex: /.*\.bilivideo\.(com|cn).*\/live-bvc\/.*m4s/,
  blackList: true,
  state: false
}

// Instagram CDN cleanup
{
  regex: /(^https:\/\/scontent[a-z0-9-]*\.cdninstagram\.com\/.*)&bytestart=.*/,
  ext: '',
  blackList: false,
  state: false
}
```

--------------------------------

### Execute Complete Download Flow

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/api-reference/downloader-api.md

Demonstrates the full lifecycle from data preparation and downloader initialization to event listener setup and execution.

```javascript
// 1. Prepare data
const mediaData = {
  url: 'https://example.com/video.mp4',
  downFileName: 'my-video.mp4',
  tabId: 123,
  requestHeaders: {Referer: 'https://example.com'}
};

// 2. Create downloader
const downloader = new Downloader([mediaData]);

// 3. Setup listeners
downloader.on('itemProgress', (frag, state, received, total, percent) => {
  console.log(`Progress: ${percent}%`);
});

downloader.on('completed', (buffer, frag) => {
  console.log(`Downloaded: ${frag.downFileName}`);
  if (G.downAutoClose) {
    closeTab();
  }
});

downloader.on('failed', (error, frag) => {
  console.error(`Error: ${error.message}`);
});

// 4. Start download
downloader.downloader(mediaData);
```

--------------------------------

### MPD Parser Configuration Parameters

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/api-reference/media-detection.md

Example data object structure required for initializing the MPD parser.

```javascript
{
  url: 'https://example.com/manifest.mpd',
  title: 'Video Title',
  parsing: 'mpd',
  tabId: 123,
  requestHeaders: {Referer: 'https://example.com'}
}
```

--------------------------------

### M3U8 Parser Configuration Parameters

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/api-reference/media-detection.md

Example data object structure required for initializing the M3U8 parser.

```javascript
{
  url: 'https://example.com/stream.m3u8',
  title: 'Video Title',
  parsing: 'm3u8',
  tabId: 123,
  requestHeaders: {Referer: 'https://example.com'}
}
```

--------------------------------

### Send addMedia Message

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/api-reference/message-api.md

Example of sending an addMedia message to the background script.

```javascript
chrome.runtime.sendMessage({
  Message: "addMedia",
  url: "https://example.com/video.m3u8",
  href: "https://example.com/watch?v=123",
  extraExt: "m3u8",
  mime: "application/vnd.apple.mpegurl",
  requestHeaders: {Referer: "https://example.com"}
}, (res) => {
  console.log(res);  // "ok"
});
```

--------------------------------

### setHeaders Usage Example

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/api-reference/utility-functions.md

Applies headers to a specific request within a target tab.

```javascript
setHeaders([
  {
    requestId: 123,
    url: 'https://example.com/video.mp4',
    requestHeaders: {Referer: 'https://example.com'},
    cookie: 'session=abc123'
  }
], () => console.log('Headers applied'), 456);
```

--------------------------------

### Send FFmpeg Integration Message

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/api-reference/message-api.md

Example of sending a message to the background script to initiate an FFmpeg operation.

```javascript
chrome.runtime.sendMessage({
  Message: "catCatchFFmpeg",
  tabId: 123,
  active: false,
  operation: "merge",
  files: ["file1.m3u8", "file2.m3u8"]
}, (res) => {
  console.log(res);  // "ok"
});
```

--------------------------------

### getRemoteFileSize Usage Example

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/api-reference/utility-functions.md

Retrieves file size and handles the promise result.

```javascript
getRemoteFileSize('https://example.com/video.mp4')
  .then(size => console.log(`File size: ${byteToSize(size)}`))
  .catch(err => console.log('Size retrieval failed'));
```

--------------------------------

### Inject i18n script via message

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/api-reference/message-api.md

Example of injecting internationalization support into a tab.

```javascript
chrome.runtime.sendMessage({
  Message: "scriptI18n",
  tabId: 123
}, (res) => {
  console.log(res);  // "ok"
});
```

--------------------------------

### Handle Type Mismatches

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/errors.md

Examples of how specific utility functions behave when provided with incorrect data types.

```javascript
secToTime("not a number");  // Returns NaN string
byteToSize("string");       // Returns 0
isEmpty({});               // Returns false (object is not empty)
```

--------------------------------

### Send send2local Message

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/api-reference/message-api.md

Example of sending a send2local message. Requires G.send2local to be enabled and a configured G.send2localURL.

```javascript
chrome.runtime.sendMessage({
  Message: "send2local",
  action: "download",
  data: {url: "https://example.com/file.mp4", title: "Video"},
  tabId: 123
}, (res) => {
  console.log(res);  // "ok"
});
```

--------------------------------

### Inject or remove scripts via message

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/api-reference/message-api.md

Examples of injecting and removing scripts with optional page refresh.

```javascript
// Inject catch.js with page reload
chrome.runtime.sendMessage({
  Message: "script",
  script: "catch.js",
  tabId: 123,
  refresh: true
}, (res) => {
  console.log(res);  // "ok"
});

// Remove search.js without reload
chrome.runtime.sendMessage({
  Message: "script",
  script: "search.js",
  tabId: 123,
  refresh: false
}, (res) => {
  console.log(res);  // "ok"
});
```

--------------------------------

### Detect JSON Media API Response

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/api-reference/media-detection.md

Example structure of an API response containing media URLs for detection.

```javascript
// API response with media URLs
{
  "videos": [
    {"url": "https://cdn.example.com/1.mp4", "title": "Video 1"},
    {"url": "https://cdn.example.com/2.mp4", "title": "Video 2"}
  ]
}
```

--------------------------------

### Implement HEAD Request Fallback

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/errors.md

Automatically fallback to a GET request with a Range header if a HEAD request fails to return a content-length.

```javascript
fetch(url, {method: "HEAD"})
  .then(res => {
    const size = parseInt(res.headers.get("content-length"));
    if (size && !isNaN(size)) return size;
    throw new Error("HEAD no content-length");
  })
  .catch(() => {
    // Fallback to GET with Range
    return fetch(url, {
      method: "GET",
      headers: {Range: "bytes=0-0"}
    });
  });
```

--------------------------------

### Open Parser

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/api-index.md

Initializes the media parser with specific URL, title, and parsing configuration.

```javascript
openParser(
  {
    url: 'https://example.com/stream.m3u8',
    title: 'Video Title',
    parsing: 'm3u8'
  },
  {autoDown: true}
);
```

--------------------------------

### Send damnUrlHas Message

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/api-reference/message-api.md

Example of checking if a specific tab is restricted.

```javascript
chrome.runtime.sendMessage({Message: "damnUrlHas", tabId: 123}, (isRestricted) => {
  console.log(isRestricted ? 'Tab restricted' : 'Tab allowed');
});
```

--------------------------------

### constructor(data)

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/api-reference/downloader-api.md

Initializes a new Downloader instance with an array of media items to be downloaded.

```APIDOC
## constructor(data)

### Description
Initializes a new Downloader instance with media items to download.

### Parameters
- **data** (array) - Required - Array of media objects to download

### Example
```javascript
const data = [
  {
    url: 'https://example.com/video1.mp4',
    downFileName: 'video1.mp4',
    tabId: 123
  },
  {
    url: 'https://example.com/video2.mp4',
    downFileName: 'video2.mp4',
    tabId: 123
  }
];

const downloader = new Downloader(data);
```
```

--------------------------------

### Open Parser with Required Parameters

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/errors.md

Demonstrates the correct usage of openParser by providing both the url and title parameters.

```javascript
// Wrong - will fail
openParser({title: "Video"});  // Missing url

// Correct
openParser({
  url: "https://example.com/stream.m3u8",
  title: "Video Title"
});
```

--------------------------------

### Initialize Downloader Instance

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/api-reference/downloader-api.md

Creates a new instance of the Downloader class using an array of media objects.

```javascript
new Downloader(data: object[])
```

```javascript
const data = [
  {
    url: 'https://example.com/video1.mp4',
    downFileName: 'video1.mp4',
    tabId: 123
  },
  {
    url: 'https://example.com/video2.mp4',
    downFileName: 'video2.mp4',
    tabId: 123
  }
];

const downloader = new Downloader(data);
```

--------------------------------

### Manage Media Downloads

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/README.md

Initialize the Downloader class and attach event listeners to track progress and handle completion.

```javascript
// Create downloader
const downloader = new Downloader(mediaArray);

// Track progress
downloader.on('itemProgress', (frag, state, received, total, percent) => {
  console.log(`${frag.downFileName}: ${percent}%`);
});

// Handle completion
downloader.on('completed', (buffer, fragment) => {
  console.log(`Downloaded: ${fragment.downFileName}`);
});

// Start download
downloader.downloader(mediaArray[0]);
```

--------------------------------

### Remove script via closeScript message

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/api-reference/message-api.md

Example of removing a specific script from a tab.

```javascript
chrome.runtime.sendMessage({
  Message: "closeScript",
  script: "search.js",
  tabId: 123
}, (res) => {
  console.log(res);  // "ok"
});
```

--------------------------------

### Get tab feature states

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/api-reference/message-api.md

Retrieves the current state of features for a specific tab ID.

```javascript
Message: {
  Message: "getButtonState",
  tabId: number
}
```

```javascript
{
  MobileUserAgent: boolean,     // Mobile UA simulation enabled
  AutoDown: boolean,             // Auto-download enabled
  enable: boolean,               // Extension enabled
  search: boolean,               // Deep search script active
  catch: boolean,                // Cache capture script active
  recorder: boolean              // Video recorder script active
}
```

```javascript
chrome.runtime.sendMessage({Message: "getButtonState", tabId: 123}, (state) => {
  console.log(state);
  // {MobileUserAgent: false, AutoDown: true, enable: true, search: false, ...}
});
```

--------------------------------

### Apply Download Settings

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/api-reference/downloader-api.md

Logic for applying thread counts, stream modes, and FFmpeg integration based on global settings.

```javascript
// Thread count
const threads = G.M3u8Thread || 6;

// Stream mode
if (G.downStream || G.M3u8StreamSaver) {
  fragment.fileStream = streamSaver.createWriteStream(filename).getWriter();
}

// FFmpeg integration
if (G.M3u8Ffmpeg && downloadComplete) {
  chrome.runtime.sendMessage({Message: "catCatchFFmpeg", ...});
}
```

--------------------------------

### Initialize Stream Parsers

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/README.md

Open HLS or DASH parsers by providing the stream URL, title, and parsing format.

```javascript
// Open HLS parser
openParser({
  url: 'https://example.com/stream.m3u8',
  title: 'My Video',
  parsing: 'm3u8'
}, {autoDown: true});

// Open DASH parser
openParser({
  url: 'https://example.com/manifest.mpd',
  title: 'My Video',
  parsing: 'mpd'
});
```

--------------------------------

### Configure concurrent downloads

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/api-reference/downloader-api.md

Demonstrates how to manage parallel downloads, which are automatically queued based on the M3u8Thread configuration.

```javascript
const MAX_CONCURRENT = 6;  // Configure via M3u8Thread

// Downloads are automatically queued and executed concurrently
data.forEach((fragment, index) => {
  fragment.index = index;
  downloader.downloader(fragment);
  // Only MAX_CONCURRENT running at once
});
```

--------------------------------

### enable

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/api-reference/message-api.md

Toggles the extension's global enabled state and persists the change to storage.

```APIDOC
## enable

### Description
Toggles the extension's global enabled state. Updates the internal state, persists to sync storage, and updates the extension icon.

### Parameters
- **Message** (string) - Required - Must be "enable"

### Response
- **boolean** - The new enabled state of the extension.
```

--------------------------------

### Setting Name Reference Mapping

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/INDEX.md

Mapping of configuration settings to their documentation source files.

```javascript
enable                 → configuration.md:General Settings
M3u8Thread            → configuration.md:M3U8/HLS Parser Options
send2localURL         → configuration.md:Local Integration
mqttBroker            → configuration.md:MQTT Integration
blockUrl              → configuration.md:Content Blocking
```

--------------------------------

### Download Flow Diagram

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/api-index.md

Visual representation of the resource download process, including concurrent fragment handling and optional FFmpeg integration.

```text
User selects resources
    ↓
downloader.html (or m3u8.html, mpd.html)
    ↓
Create Downloader instance
    ↓
Download fragments concurrently
    ↓ (events)
Update progress UI
    ↓
Complete or error
    ↓
Optional: Send to FFmpeg
```

--------------------------------

### Check Extension Storage

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/errors.md

Retrieve and log all items from local and sync storage via the browser console.

```javascript
// In DevTools console
chrome.storage.local.get(null, (items) => {
  console.log('Local storage:', items);
});

chrome.storage.sync.get(null, (items) => {
  console.log('Sync storage:', items);
});
```

--------------------------------

### Trigger media detection on network response

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/api-reference/media-detection.md

Example of hooking into the Chrome webRequest API to trigger the detection logic.

```javascript
// Network request triggers detection
chrome.webRequest.onResponseStarted.addListener((data) => {
  try {
    findMedia(data);  // Auto-detect media
  } catch (e) {
    console.log(e);
  }
});
```

--------------------------------

### Implement Download Error Recovery

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/api-reference/downloader-api.md

Demonstrates how to handle download failures and implement a retry mechanism with exponential backoff.

```javascript
downloader.on('failed', (error, fragment) => {
  console.error(`Download failed: ${error.message}`);
  
  // Retry logic
  if (fragment.retryCount < 3) {
    fragment.retryCount = (fragment.retryCount || 0) + 1;
    console.log(`Retrying (${fragment.retryCount}/3)...`);
    
    // Wait before retry
    setTimeout(() => {
      downloader.downloader(fragment);
    }, 1000 * fragment.retryCount);
  }
});
```

--------------------------------

### Configuration Option Categories

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/INDEX.md

Summary of available configuration options categorized by functionality.

```text
Media filtering:    5+ extension types
                   9+ MIME types
                   4+ regex patterns
Download options:  8 options
Parser options:    8 M3U8 options
Integration:       20+ Send2Local + MQTT + Aria2 options
UI options:        10+ options
```

--------------------------------

### openParser(mediaInfo, options)

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/api-index.md

Opens the media parser for a specific URL with optional configuration.

```APIDOC
## openParser(mediaInfo, options)

### Description
Triggers the media parser to process a specific media item.

### Parameters
- **mediaInfo** (object) - Required - Contains url, title, and parsing type.
- **options** (object) - Optional - Configuration options such as autoDown.
```

--------------------------------

### downloader.on('itemProgress', callback)

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/api-reference/downloader-api.md

Registers a listener for download progress updates to synchronize UI elements like progress bars and file size displays.

```APIDOC
## downloader.on('itemProgress', callback)

### Description
Registers a callback function that triggers whenever a download fragment reports progress. Use this to update UI components such as progress bars and text labels.

### Parameters
- **fragment** (Object) - The current download fragment being processed.
- **state** (String) - The current state of the download.
- **receivedLength** (Number) - The number of bytes received so far.
- **contentLength** (Number) - The total size of the content in bytes.
```

--------------------------------

### Download Configuration Object

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/api-reference/downloader-api.md

Definition of the downloader configuration options available in G.OptionLists.

```javascript
// From G.OptionLists
{
  downActive: boolean,      // Enable/disable
  downAutoClose: boolean,   // Close after finish
  downStream: boolean,      // Stream to disk
  M3u8Thread: number,       // Concurrent threads
  M3u8StreamSaver: boolean, // Use StreamSaver
  M3u8Ffmpeg: boolean       // Send to FFmpeg
}
```

--------------------------------

### Download Control UI Structure

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/api-reference/downloader-api.md

HTML structure for displaying download items with progress bars and control buttons.

```html
<div class="downItem">
  <div class="explain">video.mp4</div>
  <div class="progress-container">
    <div class="progress-bar">
      <div class="progress"></div>
      <span class="progress-text">0%</span>
    </div>
    <button class="cancel-btn">Stop Download</button>
  </div>
</div>
```

--------------------------------

### Inspect Extension Storage

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/README.md

Retrieve and log all data from local or sync storage via the DevTools console.

```javascript
// In DevTools console
chrome.storage.local.get(null, d => console.log('Local:', d));
chrome.storage.sync.get(null, d => console.log('Sync:', d));
```

--------------------------------

### Define MQTT Configuration Structure

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/types.md

Represents the schema for MQTT broker integration settings.

```javascript
{
  send2MQTT: boolean,
  mqttEnable: boolean,
  mqttBroker: string,
  mqttPort: number,
  mqttPath: string,
  mqttProtocol: string,
  mqttClientId: string,
  mqttUser: string,
  mqttPassword: string,
  mqttTopic: string,
  mqttQos: number,
  mqttTitleLength: number,
  mqttDataFormat: string
}
```

--------------------------------

### Format and Parse Data with Utility Functions

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/README.md

Use these helper functions for formatting time, file sizes, bitrates, sanitizing filenames, and safe JSON parsing.

```javascript
// Format data for display
const timeStr = secToTime(3661);        // "1:01:01"
const sizeStr = byteToSize(1048576);    // "1.0 MB"
const rateStr = formatBitrate(5000000); // "5.00 Mbps"

// Manipulate filenames
const clean = filterFileName('my:file*.mp4'); // "my&colon;file&ast;.mp4"

// Parse JSON safely
const data = JSONparse(jsonString);
```

--------------------------------

### Enable Logging in Extension

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/README.md

Use standard console logging within the extension environment to output debug messages.

```javascript
// In extension code
console.log('Debug message');
```

--------------------------------

### MQTT Publishing Configuration

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/README.md

Protocol and topic settings for publishing media data to an MQTT broker.

```text
Protocol: WebSocket (wss/ws)
Topic: cat-catch/media
Format: JSON (configurable)
```

--------------------------------

### Download a single file

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/api-reference/downloader-api.md

Initializes the Downloader with a single file object and triggers the download process.

```javascript
const data = [{
  url: 'https://example.com/movie.mp4',
  downFileName: 'movie.mp4',
  tabId: 123,
  requestId: 'req_1'
}];

const downloader = new Downloader(data);
downloader.downloader(data[0]);
```

--------------------------------

### Downloader.downloader(fragment)

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/types.md

Initiates the download process for a single fragment.

```APIDOC
## downloader(fragment)

### Description
Downloads a single fragment from the provided list.

### Parameters
- **fragment** (Fragment) - Required - The fragment object to download.

### Returns
- **Promise** - Resolves when the download is complete.
```

--------------------------------

### Downloader.on(event, callback)

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/types.md

Registers an event listener for download events.

```APIDOC
## on(event, callback)

### Description
Registers a callback function for specific download events.

### Parameters
- **event** (string) - Required - The event name (itemProgress, completed, failed).
- **callback** (function) - Required - The function to execute when the event occurs.
```

--------------------------------

### downloader(fragment)

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/api-reference/downloader-api.md

Initiates the download of a single media fragment.

```APIDOC
## downloader(fragment)

### Description
Downloads a single media fragment or segment. Returns a Promise that resolves when the download completes or rejects on error.

### Parameters
- **fragment** (object) - Required - The fragment/media item to download. Must contain properties: url, downFileName, fileStream (optional), requestHeaders (optional), and mime.

### Returns
- **Promise** - Resolves when download completes or rejects on error.
```

--------------------------------

### Configure File Extensions

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/types.md

Defines the schema for filtering media files based on extension, size, and enabled state.

```javascript
{
  ext: string,
  size: number,
  operator: string,
  unit: string,
  state: boolean
}
```

```javascript
{
  ext: "mp4",
  size: 0,
  operator: ">=",
  unit: "KB",
  state: true
}
```

--------------------------------

### Search Function Documentation

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/INDEX.md

Use grep to locate specific function definitions within the utility and message API documentation files.

```bash
# Find function documentation
grep -n "^### \`functionName\`" api-reference/utility-functions.md
grep -n "^### \`getMessage\`" api-reference/message-api.md
```

--------------------------------

### openParser(params)

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/errors.md

Opens the parser UI. Requires both 'url' and 'title' parameters to function correctly.

```APIDOC
## openParser(params)

### Description
Opens the parser UI. If required parameters are missing, the UI will fail to display media.

### Parameters
- **url** (string) - Required - The URL of the media to parse.
- **title** (string) - Required - The title of the media.

### Example
```javascript
openParser({
  url: "https://example.com/stream.m3u8",
  title: "Video Title"
});
```
```

--------------------------------

### MQTT Integration

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/api-index.md

Publishes media data to an MQTT broker.

```APIDOC
## MQTT Integration

### Description
Publishes detected media data to a specific MQTT topic.

### Topic
cat-catch/media

### Payload
- **mediaItem** (object) - The media data object
```

--------------------------------

### Download Configuration Settings

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/api-reference/downloader-api.md

Defines the available configuration options for controlling download behavior.

```APIDOC
## Download Configuration Settings

### Description
Configuration object used to define download behavior, including concurrency, streaming, and post-processing.

### Fields
- **downActive** (boolean) - Enable or disable the downloader.
- **downAutoClose** (boolean) - Automatically close the download task after completion.
- **downStream** (boolean) - Enable streaming directly to disk.
- **M3u8Thread** (number) - Number of concurrent threads for M3u8 downloads.
- **M3u8StreamSaver** (boolean) - Use StreamSaver for file saving.
- **M3u8Ffmpeg** (boolean) - Send completed downloads to FFmpeg for processing.
```

--------------------------------

### Search Message Documentation

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/INDEX.md

Locate message type definitions and documentation entries using grep patterns.

```bash
# Find message documentation
grep -n "^### \`\${Message}\`" api-reference/message-api.md
grep -r "Message: \"type\"" api-reference/message-api.md
```

--------------------------------

### Downloader Class

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/api-reference/downloader-api.md

The Downloader class allows for the initialization of download tasks and provides event-driven feedback on download progress and status.

```APIDOC
## Downloader Class

### Description
The Downloader class is used to manage media download tasks. It supports event listeners for tracking progress and handling completion or failure states.

### Constructor
`new Downloader(items)`
- **items** (Array) - An array of media data objects containing `url`, `downFileName`, `tabId`, and `requestHeaders`.

### Methods
#### downloader(mediaData)
Starts the download process for the provided media data.
- **mediaData** (Object) - The media object to download.

### Events
- **itemProgress** (frag, state, received, total, percent) - Emitted when download progress updates.
- **completed** (buffer, frag) - Emitted when a download finishes successfully.
- **failed** (error, frag) - Emitted when a download encounters an error.
```

--------------------------------

### Download a media fragment

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/api-reference/downloader-api.md

Initiates a download for a specific fragment object using the downloader method.

```javascript
downloader(fragment: Fragment): Promise
```

```javascript
const fragment = {
  url: 'https://example.com/file.mp4',
  downFileName: 'movie.mp4',
  index: 0,
  requestHeaders: {Referer: 'https://example.com'}
};

downloader.downloader(fragment)
  .then(() => console.log('Download complete'))
  .catch(err => console.error('Download failed', err));
```

--------------------------------

### Wait for Global Variable Initialization

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/errors.md

Ensures global variables are ready for use by wrapping logic in an awaitG call.

```javascript
awaitG(() => {
  // G is now ready
  console.log(G.enable, G.version);
});
```

--------------------------------

### Await Global Variable Initialization

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/api-reference/utility-functions.md

Executes a callback once both G.initSyncComplete and G.initLocalComplete are true. The optional sec parameter defines the polling interval in milliseconds.

```javascript
function awaitG(callback: function, sec?: number): void
```

```javascript
awaitG(() => {
  console.log('G is ready');
  console.log(G.enable, G.version);
});
```

--------------------------------

### Trigger Custom Download via Local Service

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/api-index.md

Sends media metadata to a local service for processing.

```javascript
// Send to local service
send2local('download', {
  url: media.url,
  title: media.title,
  headers: media.requestHeaders
}, currentTabId).then(() => {
  console.log('Sent to local service');
});
```

--------------------------------

### Handle Download Progress Events

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/api-reference/downloader-api.md

Updates the UI progress bar and file size text based on fragment download events.

```javascript
downloader.on('itemProgress', (fragment, state, receivedLength, contentLength) => {
  const itemDOM = itemDOM.get(fragment.index);
  
  // Update progress bar
  const percent = (receivedLength / contentLength * 100).toFixed(2);
  itemDOM.progress(percent);
  
  // Update file size display
  const text = `${byteToSize(receivedLength)} / ${byteToSize(contentLength)}`;
  itemDOM.downFileProgress(text);
});
```

--------------------------------

### Define Default Blocked Domains

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/api-reference/media-detection.md

Initializes the global blocked URL patterns and the runtime blocked tab set.

```javascript
G.damnUrl = [
  /^https:\/\/.*\.douyin\.com\/.*$/i,  // TikTok/Douyin
];
G.damnUrlSet = new Set();  // Runtime blocked tab IDs
```

--------------------------------

### openParser

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/README.md

Function to trigger the extension's media parser for HLS or DASH streams.

```APIDOC
## openParser(mediaInfo, options)

### Description
Opens the internal parser for a specific media stream URL.

### Parameters
- **mediaInfo** (object) - Required - Contains 'url', 'title', and 'parsing' (m3u8 or mpd).
- **options** (object) - Optional - Configuration such as {autoDown: boolean}.
```

--------------------------------

### Extension Permissions Configuration

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/api-index.md

JSON configuration defining the required browser permissions for extension functionality.

```json
{
  "permissions": [
    "tabs",              // Access tab information
    "webRequest",        // Monitor network traffic
    "downloads",         // Control downloads
    "storage",           // Persistent storage
    "webNavigation",     // Track navigation
    "alarms",            // Schedule background tasks
    "declarativeNetRequest",  // Modify headers
    "scripting",         // Inject scripts
    "sidePanel",         // Side panel UI
    "contextMenus"       // Context menu items
  ]
}
```

--------------------------------

### Function Reference Mapping

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/INDEX.md

Mapping of core utility functions and classes to their documentation source files.

```javascript
secToTime()           → api-reference/utility-functions.md:secToTime
filterFileName()      → api-reference/utility-functions.md:filterFileName
send2local()          → api-reference/utility-functions.md:send2local
downloadDataURL()     → api-reference/utility-functions.md:downloadDataURL
Downloader()          → api-reference/downloader-api.md:Downloader Class
```

--------------------------------

### Perform batch downloads

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/api-reference/downloader-api.md

Iterates through an array of file objects to download multiple media files sequentially.

```javascript
const data = [
  {url: 'https://example.com/1.mp4', downFileName: '1.mp4'},
  {url: 'https://example.com/2.mp4', downFileName: '2.mp4'},
  {url: 'https://example.com/3.mp4', downFileName: '3.mp4'}
];

const downloader = new Downloader(data);

// Download all
data.forEach((fragment, index) => {
  fragment.index = index;
  downloader.downloader(fragment);
});
```

--------------------------------

### Handle Empty Data in send2local

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/errors.md

Shows how to handle rejected promises when sending empty data objects to the local storage.

```javascript
send2local(action, data, tabId)  // data = null or {}
  .then(res => {
    if (!res.ok) {
      console.error('Empty data rejected');
    }
  });
```

--------------------------------

### Search Data Type Documentation

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/INDEX.md

Search for specific type definitions within the types documentation file using case-insensitive grep.

```bash
# Find type documentation
grep -n "^## " types.md | grep -i "typename"
grep -n "^### " types.md | grep -i "typename"
```

--------------------------------

### Extension Component Structure

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/api-index.md

Visual representation of the file structure and component responsibilities.

```text
popup.html              (UI for resource list)
  ├── popup.js         (Popup logic)
  └── popup-utils.js   (UI utilities)

background.js          (Service worker - detection/caching)
  ├── Media detection
  ├── Message routing
  └── Cache management

downloader.html        (File download UI)
  ├── downloader.js    (Download management)
  └── UI components

m3u8.html              (HLS parser UI)
  ├── m3u8.js         (Segment parsing)
  ├── m3u8.downloader.js
  └── hls.js (3rd party)

mpd.html               (DASH parser UI)
  └── mpd.js          (Manifest parsing)

catch-script/          (Content scripts)
  ├── catch.js        (Capture script)
  ├── search.js       (Deep search)
  ├── recorder.js     (Video recording)
  └── webrtc.js       (Recording utilities)

content-script.js      (Page-level detection)
```

--------------------------------

### Toggle extension enabled state

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/api-reference/message-api.md

Sends an enable message to toggle the global extension state and persist the change to sync storage.

```javascript
Message: {
  Message: "enable"
}
```

```javascript
chrome.runtime.sendMessage({Message: "enable"}, (isEnabled) => {
  console.log(isEnabled ? 'Enabled' : 'Disabled');
});
```

--------------------------------

### Configure File Extension Filtering

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/configuration.md

Defines the default file extension detection and size filtering rules within the G.OptionLists.Ext array.

```javascript
G.OptionLists.Ext = [
  {ext: "flv", size: 0, operator: ">=", unit: "KB", state: true},
  {ext: "hlv", size: 0, operator: ">=", unit: "KB", state: true},
  {ext: "f4v", size: 0, operator: ">=", unit: "KB", state: true},
  {ext: "mp4", size: 0, operator: ">=", unit: "KB", state: true},
  {ext: "mp3", size: 0, operator: ">=", unit: "KB", state: true},
  {ext: "wma", size: 0, operator: ">=", unit: "KB", state: true},
  {ext: "wav", size: 0, operator: ">=", unit: "KB", state: true},
  {ext: "m4a", size: 0, operator: ">=", unit: "KB", state: true},
  {ext: "ts", size: 0, operator: ">=", unit: "KB", state: false},
  {ext: "webm", size: 0, operator: ">=", unit: "KB", state: true},
  {ext: "ogg", size: 0, operator: ">=", unit: "KB", state: true},
  {ext: "ogv", size: 0, operator: ">=", unit: "KB", state: true},
  {ext: "acc", size: 0, operator: ">=", unit: "KB", state: true},
  {ext: "mov", size: 0, operator: ">=", unit: "KB", state: true},
  {ext: "mkv", size: 0, operator: ">=", unit: "KB", state: true},
  {ext: "m4s", size: 0, operator: ">=", unit: "KB", state: true},
  {ext: "m3u8", size: 0, operator: ">=", unit: "KB", state: true},
  {ext: "m3u", size: 0, operator: ">=", unit: "KB", state: true},
  {ext: "mpeg", size: 0, operator: ">=", unit: "KB", state: true},
  {ext: "avi", size: 0, operator: ">=", unit: "KB", state: true},
  {ext: "wmv", size: 0, operator: ">=", unit: "KB", state: true},
  {ext: "asf", size: 0, operator: ">=", unit: "KB", state: true},
  {ext: "movie", size: 0, operator: ">=", unit: "KB", state: true},
  {ext: "divx", size: 0, operator: ">=", unit: "KB", state: true},
  {ext: "mpeg4", size: 0, operator: ">=", unit: "KB", state: true},
  {ext: "vid", size: 0, operator: ">=", unit: "KB", state: true},
  {ext: "aac", size: 0, operator: ">=", unit: "KB", state: true},
  {ext: "mpd", size: 0, operator: ">=", unit: "KB", state: true},
  {ext: "weba", size: 0, operator: ">=", unit: "KB", state: true},
  {ext: "opus", size: 0, operator: ">=", unit: "KB", state: true},
  {ext: "srt", size: 0, operator: ">=", unit: "KB", state: false},
  {ext: "vtt", size: 0, operator: ">=", unit: "KB", state: false}
]
```

--------------------------------

### Integration Flow Diagram

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/api-index.md

Visual representation of the data integration process for sending detected media to local services.

```text
Media detected
    ↓
send2local() called
    ↓
Template substitution
    ↓
HTTP POST/GET to endpoint
    ↓
Local service receives data
```

--------------------------------

### getAllData

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/api-reference/message-api.md

Retrieves all cached media data from the extension.

```APIDOC
## getAllData

### Description
Retrieves all cached media data from the extension.

### Parameters
- **Message** (string) - Required - Must be "getAllData"

### Response
- **Response** (object) - Complete cache data object with tabId keys
```

--------------------------------

### Downloader Management API

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/INDEX.md

Interface for initializing, controlling, and monitoring download progress via event listeners.

```javascript
// Located in: api-reference/downloader-api.md
const downloader = new Downloader(data)
downloader.downloader(fragment)
downloader.stop(index)
downloader.on('itemProgress', (f, state, rx, tx, pct) => {...})
downloader.on('completed', (buf, frag) => {...})
downloader.on('failed', (err, frag) => {...})
```

--------------------------------

### Configure Regex URL Patterns

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/configuration.md

Defines URL pattern matching rules for specialized media detection within the G.OptionLists.Regex array.

```javascript
G.OptionLists.Regex = [
  {type: "ig", regex: "https://cache\\.video\\.[a-z]*\\.com/dash\\?tvid=.*", ext: "json", state: false},
  {type: "ig", regex: ".*\\.bilivideo\\.(com|cn).*\\/live-bvc\\/.*m4s", ext: "", blackList: true, state: false},
  {type: "ig", regex: "(^https://scontent[a-z0-9-]*\\.cdninstagram\\.com/.*)&bytestart=.*", ext: "", blackList: false, state: false},
  {type: "ig", regex: "(^https://.*\\.fbcdn\\.net/.*)&bytestart=.*", ext: "", blackList: false, state: false}
]
```

--------------------------------

### openParser(data, options)

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/api-reference/utility-functions.md

Opens the media parser interface for m3u8, mpd, or json formats in a new tab with pre-filled parameters.

```APIDOC
## openParser(data, options)

### Description
Opens media parser interface (m3u8, mpd, json) in a new tab with pre-filled parameters.

### Signature
`function openParser(data: object, options?: object): void`

### Parameters
- **data** (object) - Required - Media data object containing url, title, downFileName, tabId, initiator, requestHeaders, and parsing type.
- **options** (object) - Optional - Parser options including autoDown, retryCount, and getMpdId.

### Example
```javascript
openParser(
  {
    url: 'https://example.com/stream.m3u8',
    title: 'Video Title',
    parsing: 'm3u8'
  },
  {autoDown: true}
);
```

--------------------------------

### Manage Sync and Local Storage Usage

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/errors.md

Use local storage for large data to avoid sync storage limits and reserve sync storage for settings.

```javascript
// Use local storage for cache (not synced)
chrome.storage.local.set({MediaData: cacheData});

// Use sync storage only for settings
chrome.storage.sync.set({enable: true, checkDuplicates: true});
```

--------------------------------

### send2local(action, data, tabId)

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/errors.md

Sends data to the local environment. Rejects empty data objects.

```APIDOC
## send2local(action, data, tabId)

### Description
Sends data to a local destination. Providing null or an empty object for the 'data' parameter will result in a rejection.

### Example
```javascript
send2local(action, data, tabId)
  .then(res => {
    if (!res.ok) {
      console.error('Empty data rejected');
    }
  });
```
```

--------------------------------

### Error Handling and Recovery

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/api-reference/downloader-api.md

Guidelines for managing download failures and implementing retry logic.

```APIDOC
## Error Handling

### Common Errors
- **NetworkError**: Connection lost. Recovery: Retry with exponential backoff.
- **TypeError**: Invalid URL. Recovery: Check URL format and headers.
- **NotAllowedError**: CORS or permissions. Recovery: Verify headers and endpoint.
- **StorageError**: Disk full or quota exceeded. Recovery: Check storage space.

### Error Recovery Example
```javascript
downloader.on('failed', (error, fragment) => {
  console.error(`Download failed: ${error.message}`);
  if (fragment.retryCount < 3) {
    fragment.retryCount = (fragment.retryCount || 0) + 1;
    setTimeout(() => {
      downloader.downloader(fragment);
    }, 1000 * fragment.retryCount);
  }
});
```
```

--------------------------------

### Format bitrate with formatBitrate

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/api-reference/utility-functions.md

Converts bits per second into a human-readable Mbps or kbps string.

```javascript
function formatBitrate(bps: number): string
```

```javascript
formatBitrate(5000000)  // Returns "5.00 Mbps"
formatBitrate(256000)   // Returns "250.00 kbps"
```

--------------------------------

### Execute core HTTP request

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/api-reference/utility-functions.md

Performs a request with support for multiple HTTP methods, content types, and template substitution.

```javascript
function executeCoreRequest(postData: object | string, templateContext: object): Promise<Response>
```

```javascript
executeCoreRequest(
  {message: 'Download started'},
  {tabId: 123, action: 'download'}
).then(res => console.log('Success'));
```

--------------------------------

### Extension Data Flow

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/api-index.md

Diagram showing the lifecycle of a network request from detection to download.

```text
Web Page
    ↓
Network Requests
    ↓
background.js (findMedia)
    ↓
cacheData Map
    ↓
popup.html (display)
  ↓          ↓
Direct Download  or  Streaming Parser
    ↓
downloader.html or m3u8.html/mpd.html
    ↓
Chrome Downloads API / StreamSaver / FFmpeg
```

--------------------------------

### awaitG(callback, sec)

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/api-reference/utility-functions.md

Waits for the global variable G to be fully initialized before executing a callback function.

```APIDOC
## awaitG(callback, sec)

### Description
Waits for global variable G initialization to complete before executing the provided callback. It checks for both G.initSyncComplete and G.initLocalComplete.

### Signature
`awaitG(callback: function, sec?: number): void`

### Parameters
- **callback** (function) - Required - Function to execute when G is ready
- **sec** (number) - Optional - Polling interval in milliseconds (Default: 0)

### Example
```javascript
awaitG(() => {
  console.log('G is ready');
});
```
```

--------------------------------

### Media Detection and Parsing

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/INDEX.md

Utilities for identifying media, parsing filenames, and validating URLs.

```javascript
// Located in: api-reference/media-detection.md
findMedia(data, isRegex, filter, timer)
fileNameParse(pathname)
openParser(data, options)
isLockUrl(url)
isDamnUrl(url)
```

--------------------------------

### Open M3U8 Parser

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/api-reference/media-detection.md

Triggers the M3U8 parser with automatic download enabled.

```javascript
openParser(data, {autoDown: true})
```

--------------------------------

### Download Task Object

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/types.md

Represents a download task with metadata for file handling, request headers, and optional merge or FFmpeg processing.

```javascript
{
  url: string,
  downFileName: string,
  tabId: number,
  requestId: string | number,
  index: number,
  size?: number,
  mime?: string,
  requestHeaders?: {[key: string]: string},
  fileStream?: WritableStreamDefaultWriter,
  
  // Merge task properties
  isMaster?: boolean,
  quantity?: number,
  taskId?: string,
  ffmpeg?: boolean,
  autoClose?: boolean
}
```

--------------------------------

### M3U8 Configuration Schema

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/types.md

Defines the structure for M3U8 parser and downloader settings.

```javascript
{
  addParam: boolean,
  fold: boolean,
  m3u8dlRE: boolean,
  M3u8HideDownloadedSegments: boolean,
  M3u8Thread: number,
  M3u8Mp4: boolean,
  M3u8OnlyAudio: boolean,
  M3u8SkipDecrypt: boolean,
  M3u8StreamSaver: boolean,
  M3u8Ffmpeg: boolean,
  M3u8AutoClose: boolean,
  retryCount: number
}
```

--------------------------------

### Define FFmpeg Configuration

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/types.md

Represents the internal interface settings for FFmpeg operations.

```javascript
{
  url: string,
  version: string,
  tab?: number,
  cacheData: object[]
}
```

--------------------------------

### POST http://127.0.0.1:8000/

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/api-index.md

Sends detected media information to a local HTTP endpoint for processing.

```APIDOC
## POST http://127.0.0.1:8000/

### Description
Sends detected media data to a local HTTP server.

### Method
POST

### Endpoint
http://127.0.0.1:8000/

### Request Body
- **action** (string) - Required - The action to perform (e.g., "download")
- **data** (object) - Required - The media item details
- **tabId** (number) - Required - The ID of the tab where the media was detected
```

--------------------------------

### addMedia

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/api-reference/message-api.md

Adds a media URL to the extension cache for processing.

```APIDOC
## addMedia

### Description
Adds a media URL from a content script or injected script to the extension cache.

### Parameters
- **Message** (string) - Required - Must be "addMedia"
- **url** (string) - Required - Media URL
- **href** (string) - Required - Page URL where media was found
- **extraExt** (string) - Optional - Override file extension
- **mime** (string) - Optional - MIME type of media
- **requestId** (string) - Optional - Request ID for tracking
- **requestHeaders** (object) - Optional - HTTP headers used in request

### Response
- **Success** (string) - Returns "ok"

### Example
```javascript
chrome.runtime.sendMessage({
  Message: "addMedia",
  url: "https://example.com/video.m3u8",
  href: "https://example.com/watch?v=123",
  extraExt: "m3u8",
  mime: "application/vnd.apple.mpegurl",
  requestHeaders: {Referer: "https://example.com"}
}, (res) => {
  console.log(res);  // "ok"
});
```
```

--------------------------------

### Send message to extension from external source

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/api-reference/message-api.md

Use this method to query data from the extension by providing its specific extension ID and the required action parameters.

```javascript
chrome.runtime.sendMessage(
    "cat-catch-extension-id",
    {action: "getData", ...params},
    (response) => {
        console.log(response);
    }
);
```

--------------------------------

### Timeout Handling for Media Detection

Source: https://github.com/xifangczy/cat-catch/blob/master/_autodocs/api-reference/media-detection.md

Implements a retry mechanism for media detection that waits for global initialization to complete.

```javascript
// Media detection waits for G initialization
function findMedia(data, isRegex, filter, timer) {
  if (!G || !G.initSyncComplete) {
    if (timer) return;  // Prevent infinite retry
    
    // Retry after 500ms
    setTimeout(() => {
      findMedia(data, isRegex, filter, true);
    }, 500);
    return;
  }
  // ... continue detection
}
```
Tokens:
Raw