SeerrBridge

https://github.com/woahai321/seerrbridge
Admin
SeerrBridge is a browser automation tool that integrates Jellyseerr/Overseerr with Debrid Media...
Tokens:11,840
Snippets:57
Trust Score:8.9
Update:6 months ago
Show doc for...
Tokens:
Raw
### Background Task Scheduler Setup (Python)

Source: https://context7.com/woahai321/seerrbridge/llms.txt

This Python snippet outlines the setup for a background task scheduler using APScheduler. It imports necessary components for asynchronous scheduling, managing queues, accessing browser drivers, performing searches, and refreshing access tokens. It is intended for managing automated processes.

```python
# Python backend: Background task scheduler (seerr/background_tasks.py)
from apscheduler.schedulers.asyncio import AsyncIOScheduler
from asyncio import Queue, Semaphore
from seerr.browser import get_driver
from seerr.search import search_dmm
from seerr.realdebrid import refresh_access_token

```

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

### Configure DMM Search Automation

Source: https://context7.com/woahai321/seerrbridge/llms.txt

Initializes the Selenium WebDriver and necessary dependencies for automating torrent searches on Debrid Media Manager. This setup allows for programmatic interaction with the DMM web interface.

```python
from selenium import webdriver
from selenium.webdriver.common.by import By
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC
import re
from fuzzywuzzy import fuzz
```

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

### SeerrBridge Docker Network Configuration for Webhooks

Source: https://github.com/woahai321/seerrbridge/blob/main/README.md

This snippet illustrates how to configure the webhook URL for SeerrBridge based on the Docker networking setup. It provides different URLs depending on whether SeerrBridge and the media server are on the same Docker network, host machine, or different networks. This ensures proper communication for receiving notifications.

```bash
http://seerrbridge:8777/jellyseer-webhook/  # Same Docker network
http://localhost:8777/jellyseer-webhook/  # Host machine
```

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

### Custom Regex Filtering for Content Management

Source: https://github.com/woahai321/seerrbridge/blob/main/README.md

This section provides various regular expression patterns used for filtering unwanted content. It includes default patterns for excluding specific formatting, Cyrillic characters, and items marked as '[esp]'. Additional examples demonstrate how to incorporate resolution and torrent type filters.

```regex
^(?!.*\u3010.*?\u3011)(?!.*[\u0400-\u04FF])(?!.*..\[esp\]).*

```

```regex
^(?=.*(1080p|2160p))(?!.*\u3010.*?\u3011)(?!.*[\u0400-\u04FF])(?!.*..\[esp\]).*

```

```regex
^(?=.*(Remux|BluRay|BDRip|BRRip))(?!.*\u3010.*?\u3011)(?!.*[\u0400-\u04FF])(?!.*..\[esp\]).*

```

```regex
^(?=.*(1080p|2160p))(?=.*(Remux|BluRay|BDRip|BRRip))(?!.*\u3010.*?\u3011)(?!.*[\u0400-\u04FF])(?!.*..\[esp\]).*

```

```regex
^(?=.*(1080p|2160p)).*

```

```regex
^(?=.*(Remux|BluRay|BDRip|BRRip)).*

```

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

### POST /api/config - Update System Settings

Source: https://context7.com/woahai321/seerrbridge/llms.txt

Updates application configuration settings stored in the .env file. Supports hot-reloading for certain configurations.

```APIDOC
## POST /api/config

### Description
Updates application configuration settings stored in the .env file. Supports hot-reloading for certain configurations.

### Method
POST

### Endpoint
/api/config

### Parameters
#### Request Body
- **configs** (array) - Required - An array of configuration objects to update.
  - **config_key** (string) - Required - The key of the configuration setting.
  - **config_value** (any) - Required - The new value for the configuration setting.
  - **config_type** (string) - Required - The data type of the configuration value ('string', 'bool', 'int', 'float').

### Request Example
```json
{
  "configs": [
    {
      "config_key": "overseerr_base",
      "config_value": "http://localhost:5055",
      "config_type": "string"
    },
    {
      "config_key": "max_movie_size",
      "config_value": 5,
      "config_type": "int"
    },
    {
      "config_key": "enable_automatic_background_task",
      "config_value": true,
      "config_type": "bool"
    }
  ]
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the update was successful.
- **message** (string) - A confirmation message.

#### Response Example
```json
{
  "success": true,
  "message": "Configuration updated successfully"
}
```
```

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

### Deploy SeerrBridge Container

Source: https://github.com/woahai321/seerrbridge/blob/main/README.md

Deploys the SeerrBridge application using Docker. This command sets up the necessary volume mappings, port exposures, and environment persistence for the containerized service.

```powershell
docker run -d --name seerrbridge --restart unless-stopped -p 3777:3777 -p 8777:8777 -p 8778:8778 -p 3307:3306 -v seerrbridge_mysql_data:/var/lib/mysql -v ./logs:/app/logs -v ./data:/app/data ghcr.io/woahai321/seerrbridge:latest
```

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

### Initialize Background Task Scheduler

Source: https://context7.com/woahai321/seerrbridge/llms.txt

Sets up an asynchronous scheduler to run periodic maintenance tasks, including token refreshes and media processing checks. It leverages the APScheduler library to manage background execution loops.

```python
from apscheduler.schedulers.asyncio import AsyncIOScheduler
import asyncio

scheduler = AsyncIOScheduler()

def start_background_tasks():
    """Start all background tasks."""
    asyncio.create_task(process_movie_queue())
    asyncio.create_task(process_tv_queue())

    scheduler.add_job(refresh_tokens_task, 'interval', minutes=10, id='token_refresh')
    scheduler.add_job(check_movie_processing, 'interval', minutes=15, id='movie_check')
    scheduler.add_job(check_show_subscriptions, 'interval', minutes=60, id='subscription_check')

    scheduler.start()
    logger.info("Background tasks started")

start_background_tasks()
```

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

### SeerrBridge Container Management

Source: https://github.com/woahai321/seerrbridge/blob/main/README.md

Essential commands for managing the SeerrBridge container instance, including checking logs and stopping or removing the service.

```bash
docker logs -f seerrbridge
docker stop seerrbridge && docker rm seerrbridge
```

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

### Manage Media Lifecycle using SQLAlchemy

Source: https://context7.com/woahai321/seerrbridge/llms.txt

Functions to create tracking records for media, update their processing status, and flag failed requests with retry logic. These methods interface with a database to ensure state consistency for media requests.

```python
from seerr.database import get_db, UnifiedMedia
from datetime import datetime
from sqlalchemy import and_

def track_media_request(tmdb_id, imdb_id, media_type, title, year, overseerr_request_id, requested_seasons=None, status='pending'):
    db = get_db()
    existing = db.query(UnifiedMedia).filter(and_(UnifiedMedia.tmdb_id == tmdb_id, UnifiedMedia.media_type == media_type)).first()
    if existing:
        existing.status = status
        existing.overseerr_request_id = overseerr_request_id
        existing.updated_at = datetime.utcnow()
        if requested_seasons: existing.seasons_processing = ','.join(map(str, requested_seasons))
        db.commit()
        return existing
    media = UnifiedMedia(tmdb_id=tmdb_id, imdb_id=imdb_id, media_type=media_type, title=title, year=year, overseerr_request_id=overseerr_request_id, status=status, created_at=datetime.utcnow(), updated_at=datetime.utcnow())
    db.add(media)
    db.commit()
    db.refresh(media)
    return media

def update_media_request_status(tmdb_id, media_type, status, processing_stage=None, error_message=None):
    db = get_db()
    media = db.query(UnifiedMedia).filter(and_(UnifiedMedia.tmdb_id == tmdb_id, UnifiedMedia.media_type == media_type)).first()
    if not media: return False
    media.status = status
    media.updated_at = datetime.utcnow()
    if processing_stage: media.processing_stage = processing_stage
    if error_message:
        media.error_message = error_message
        media.error_count = (media.error_count or 0) + 1
        media.last_error_at = datetime.utcnow()
    if status == 'completed':
        media.completed_at = datetime.utcnow()
        media.is_in_queue = False
    elif status == 'processing':
        media.processing_started_at = datetime.utcnow()
        media.is_in_queue = True
    db.commit()
    return True

def mark_media_failed(tmdb_id, media_type, error_message, max_retries=3):
    db = get_db()
    media = db.query(UnifiedMedia).filter(and_(UnifiedMedia.tmdb_id == tmdb_id, UnifiedMedia.media_type == media_type)).first()
    if not media: return False
    media.status = 'failed'
    media.error_message = error_message
    media.error_count = (media.error_count or 0) + 1
    media.is_in_queue = False
    can_retry = media.error_count < max_retries
    db.commit()
    return can_retry
```

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

### Update System Settings via API (TypeScript)

Source: https://context7.com/woahai321/seerrbridge/llms.txt

Manages application configuration by updating settings in a .env file through an API endpoint. It supports hot-reloading and handles various data types (string, bool, int, float). The frontend uses a composable to send configuration updates, while the backend processes these updates and triggers a reload for credential or task changes.

```typescript
// Frontend: Update configuration via API (composables/useConfig.ts)
import { useApi } from './useApi'

const { apiCall } = useApi()

async function updateConfiguration(configs: Array<{
  config_key: string,
  config_value: any,
  config_type: 'string' | 'bool' | 'int' | 'float'
}>) {
  const response = await apiCall('/api/config', {
    method: 'POST',
    body: { configs }
  })
  return response
}

// Example: Update multiple settings
await updateConfiguration([
  {
    config_key: 'overseerr_base',
    config_value: 'http://localhost:5055',
    config_type: 'string'
  },
  {
    config_key: 'max_movie_size',
    config_value: 5,  // 5GB limit
    config_type: 'int'
  },
  {
    config_key: 'enable_automatic_background_task',
    config_value: true,
    config_type: 'bool'
  }
])

// Backend: Configuration handler (server/api/config.post.ts)
export default defineEventHandler(async (event) => {
  const body = await readBody(event)
  const { configs } = body

  // Update each configuration in .env file
  for (const config of configs) {
    const { config_key, config_value, config_type } = config

    // Convert value based on type
    let envValue = config_value
    if (config_type === 'bool') {
      envValue = config_value === true || config_value === 'true'
    } else if (config_type === 'int') {
      envValue = parseInt(String(config_value), 10)
    } else if (config_type === 'float') {
      envValue = parseFloat(String(config_value))
    }

    // Write to .env file
    setConfigInEnv(config_key, envValue)
  }

  // Trigger backend reload for credential/task changes
  if (hasCredentialChanges || hasTaskConfigChanges) {
    await fetch('http://localhost:8777/reload-env', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' }
    })
  }

  return { success: true, message: 'Configuration updated successfully' }
})
```

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

### Fetch Media Metadata from Trakt API (Python)

Source: https://context7.com/woahai321/seerrbridge/llms.txt

Integrates with the Trakt API to retrieve enriched media metadata. It implements database caching to minimize redundant API calls and reduce load on the Trakt API. Requires a Trakt API key for authentication.

```python
# Python backend: Trakt API client (seerr/trakt.py)
import requests
from seerr.config import TRAKT_API_KEY
from seerr.database import get_db, UnifiedMedia

```

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

### Jellyseerr/Overseerr Webhook Configuration

Source: https://github.com/woahai321/seerrbridge/blob/main/README.md

This snippet shows the JSON payload structure for configuring webhooks in Jellyseerr/Overseerr to send notifications to SeerrBridge. It defines placeholders for various notification event details, media information, request data, issue reports, and comments. This allows SeerrBridge to receive and process real-time updates from your media server.

```json
{
    "notification_type": "{{notification_type}}",
    "event": "{{event}}",
    "subject": "{{subject}}",
    "message": "{{message}}",
    "image": "{{image}}",
    "{{media}}": {
        "media_type": "{{media_type}}",
        "tmdbId": "{{media_tmdbid}}",
        "tvdbId": "{{media_tvdbid}}",
        "status": "{{media_status}}",
        "status4k": "{{media_status4k}}"
    },
    "{{request}}": {
        "request_id": "{{request_id}}",
        "requestedBy_email": "{{requestedBy_email}}",
        "requestedBy_username": "{{requestedBy_username}}",
        "requestedBy_avatar": "{{requestedBy_avatar}}",
        "requestedBy_settings_discordId": "{{requestedBy_settings_discordId}}",
        "requestedBy_settings_telegramChatId": "{{requestedBy_settings_telegramChatId}}"
    },
    "{{issue}}": {
        "issue_id": "{{issue_id}}",
        "issue_type": "{{issue_type}}",
        "issue_status": "{{issue_status}}",
        "reportedBy_email": "{{reportedBy_email}}",
        "reportedBy_username": "{{reportedBy_username}}",
        "reportedBy_avatar": "{{reportedBy_avatar}}",
        "reportedBy_settings_discordId": "{{reportedBy_settings_discordId}}",
        "reportedBy_settings_telegramChatId": "{{reportedBy_settings_telegramChatId}}"
    },
    "{{comment}}": {
        "comment_message": "{{comment_message}}",
        "commentedBy_email": "{{commentedBy_email}}",
        "commentedBy_username": "{{commentedBy_username}}",
        "commentedBy_avatar": "{{commentedBy_avatar}}",
        "commentedBy_settings_discordId": "{{commentedBy_settings_discordId}}",
        "commentedBy_settings_telegramChatId": "{{commentedBy_settings_telegramChatId}}"
    },
    "{{extra}}": []
}
```

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

### Real-Debrid Environment Variables Configuration

Source: https://github.com/woahai321/seerrbridge/blob/main/README.md

This snippet shows the essential environment variables required for SeerrBridge to authenticate and interact with Real-Debrid. It includes placeholders for the access token, client ID, client secret, and refresh token, which are typically obtained from the browser's local storage. These variables should be set in the .env file or via the web dashboard.

```dotenv
RD_ACCESS_TOKEN={"value":"your_token","expiry":123}
RD_CLIENT_ID=YOUR_CLIENT_ID
RD_CLIENT_SECRET=YOUR_CLIENT_SECRET
RD_REFRESH_TOKEN=YOUR_REFRESH_TOKEN
```

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

### Fetch TV Show Media Records with Progress (TypeScript)

Source: https://context7.com/woahai321/seerrbridge/llms.txt

This TypeScript code defines a frontend API endpoint to retrieve a single media item, calculating display status and progress percentage for TV shows. It also fetches season details for TV series. Dependencies include database connection utility and router parameter extraction. It returns success status, media data, and season information.

```typescript
// Frontend API endpoint: Get single media item (server/api/unified-media/[id].get.ts)
import { getDatabaseConnection } from '~/server/utils/database'

export default defineEventHandler(async (event) => {
  const id = getRouterParam(event, 'id')
  const db = await getDatabaseConnection()

  // Get media item with computed status and progress
  const [mediaRows] = await db.execute(`
    SELECT
      um.*
      CASE
        WHEN um.media_type = 'tv' AND um.seasons_processed IS NOT NULL THEN
          CASE
            WHEN JSON_EXTRACT(um.seasons_processed, '$.completed') IS NOT NULL
              AND JSON_EXTRACT(um.seasons_processed, '$.total') IS NOT NULL THEN
              CONCAT(
                JSON_EXTRACT(um.seasons_processed, '$.completed'),
                '/',
                JSON_EXTRACT(um.seasons_processed, '$.total')
              )
            ELSE um.status
          END
        ELSE um.status
      END as status_display,
      CASE
        WHEN um.media_type = 'tv' AND um.seasons_processed IS NOT NULL THEN
          ROUND(
            (JSON_EXTRACT(um.seasons_processed, '$.completed') /
             JSON_EXTRACT(um.seasons_processed, '$.total')) * 100
          )
        ELSE 0
      END as progress_percentage
    FROM unified_media um
    WHERE um.id = ?
  `, [id])

  const media = mediaRows[0]

  // For TV shows, fetch season details
  let seasons = []
  if (media.media_type === 'tv') {
    const [seasonRows] = await db.execute(`
      SELECT
        season_number,
        episode_count,
        aired_episodes,
        confirmed_episodes,
        failed_episodes,
        unprocessed_episodes,
        is_discrepant,
        discrepancy_reason,
        status
      FROM tv_seasons
      WHERE media_id = ?
      ORDER BY season_number ASC
    `, [id])

    seasons = seasonRows.map(season => ({
      ...season,
      confirmed_episodes: JSON.parse(season.confirmed_episodes || '[]'),
      failed_episodes: JSON.parse(season.failed_episodes || '[]'),
      unprocessed_episodes: JSON.parse(season.unprocessed_episodes || '[]')
    }))
  }

  return {
    success: true,
    data: { ...media, seasons }
  }
})

// Frontend usage: Fetch media details
import { useApi } from '~/composables/useApi'

const { apiCall } = useApi()

async function getMediaDetails(mediaId: number) {
  const response = await apiCall(`/api/unified-media/${mediaId}`, {
    method: 'GET'
  })

  if (response.success) {
    const media = response.data
    console.log(`Title: ${media.title}`)
    console.log(`Status: ${media.status_display}`)
    console.log(`Progress: ${media.progress_percentage}%`)

    if (media.media_type === 'tv') {
      console.log('Seasons:')
      media.seasons.forEach(season => {
        console.log(`  S${season.season_number}: ${season.confirmed_episodes.length}/${season.episode_count} episodes`)
      })
    }
  }

  return response.data
}

// Example: Get details for media ID 123
const media = await getMediaDetails(123)

```

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

### Search DMM for Torrents with Filters (Python)

Source: https://context7.com/woahai321/seerrbridge/llms.txt

Searches DMM for torrents matching a given IMDB ID, title, media type, and size limit. It navigates the DMM website using Selenium, applies regular expression filters to torrent titles, checks file sizes against specified limits, and prioritizes cached torrents (indicated by red buttons). The function clicks the best matching torrent and waits for a success indicator before returning.

```python
TORRENT_FILTER_REGEX = r"^(?!.*【.*?】)(?!.*[\u0400-\u04FF])(?!.*[esp]).*"  # Exclude Cyrillic, [esp], 【】
MAX_MOVIE_SIZE = 5  # GB
MAX_EPISODE_SIZE = 1  # GB

def search_dmm(driver, imdb_id: str, title: str, media_type: str, size_limit: float) -> bool:
    """
    Search DMM for media and add matching torrents.

    Args:
        driver: Selenium WebDriver instance
        imdb_id: IMDB ID (e.g., 'tt0137523')
        title: Media title for fallback search
        media_type: 'movie' or 'tv'
        size_limit: Maximum file size in GB

    Returns:
        bool: True if torrent(s) added successfully
    """
    # Navigate to DMM search page with IMDB ID
    search_url = f"https://debridmediamanager.com/search?query={imdb_id}"
    driver.get(search_url)

    # Wait for results to load
    WebDriverWait(driver, 10).until(
        EC.presence_of_element_located((By.CSS_SELECTOR, "a.haptic, a[href*='/movie/'], a[href*='/show/']"))
    )

    # Find all result boxes
    result_boxes = driver.find_elements(By.CSS_SELECTOR, "div[class*='Box']")

    regex_pattern = re.compile(TORRENT_FILTER_REGEX)
    matched_items = []

    for box in result_boxes:
        try:
            # Extract torrent title
            title_element = box.find_element(By.CSS_SELECTOR, "div[class*='Title']")
            torrent_title = title_element.text.strip()

            # Apply regex filter
            if not regex_pattern.match(torrent_title):
                logger.debug(f"Filtered out by regex: {torrent_title}")
                continue

            # Extract file size
            size_text = box.find_element(By.CSS_SELECTOR, "div[class*='Size']").text
            size_match = re.search(r'([\d.]+)\s*(GB|MB)', size_text, re.IGNORECASE)

            if size_match:
                size_value = float(size_match.group(1))
                size_unit = size_match.group(2).upper()

                # Convert to GB
                size_gb = size_value if size_unit == 'GB' else size_value / 1024

                # Check size limit
                if size_gb > size_limit:
                    logger.debug(f"Filtered by size ({size_gb:.2f}GB > {size_limit}GB): {torrent_title}")
                    continue

            # Check for red button (priority)
            try:
                red_button = box.find_element(By.CSS_SELECTOR, "button[class*='red']")
                priority = 1  # Red buttons = already cached/available
            except:
                priority = 2  # No red button

            matched_items.append({
                'title': torrent_title,
                'size_gb': size_gb,
                'priority': priority,
                'button': box.find_element(By.CSS_SELECTOR, "button")
            })

        except Exception as e:
            logger.<bos>debug(f"Error processing result box: {e}")
            continue

    if not matched_items:
        logger.warning(f"No torrents matched filters for {title}")
        return False

    # Sort by priority (red buttons first), then by size (larger = better quality)
    matched_items.sort(key=lambda x: (x['priority'], -x['size_gb']))

    # Click the best match
    best_match = matched_items[0]
    logger.info(f"Adding torrent: {best_match['title']} ({best_match['size_gb']:.2f}GB)")
    best_match['button'].click()

    # Wait for success indicator
    WebDriverWait(driver, 10).until(
        EC.presence_of_element_located((By.CSS_SELECTOR, "div[class*='success']"))
    )

    return True

# Example usage
from seerr.browser import get_driver

driver = get_driver()

# Search for movie
success = search_dmm(
    driver=driver,
    imdb_id='tt0137523',  # Fight Club
    title='Fight Club',
    media_type='movie',
    size_limit=MAX_MOVIE_SIZE
)

if success:
    print("Movie added to Real-Debrid library via DMM")
else:
    print("No suitable torrents found")

```

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

### Stuck Task Recovery and Subscription Monitoring

Source: https://context7.com/woahai321/seerrbridge/llms.txt

Background tasks that query the database for stuck items using exponential backoff or check for new TV show episodes via Trakt. These functions ensure system reliability by re-queuing failed tasks and automating subscription updates.

```python
async def check_movie_processing():
    db = get_db()
    stuck_movies = db.query(UnifiedMedia).filter(and_(UnifiedMedia.media_type == 'movie', UnifiedMedia.status == 'processing', UnifiedMedia.is_in_queue == False, UnifiedMedia.error_count < 3)).all()
    for movie in stuck_movies:
        if movie.last_error_at:
            hours_since_error = (datetime.utcnow() - movie.last_error_at).total_seconds() / 3600
            if hours_since_error < (2 * (2 ** movie.error_count)): continue
        await movie_queue.put({'tmdb_id': movie.tmdb_id, 'imdb_id': movie.imdb_id, 'title': movie.title, 'media_type': 'movie'})
        movie.is_in_queue = True
        db.commit()

async def check_show_subscriptions():
    db = get_db()
    subscribed_shows = db.query(UnifiedMedia).filter(and_(UnifiedMedia.media_type == 'tv', UnifiedMedia.is_subscribed == True, UnifiedMedia.subscription_active == True)).all()
    for show in subscribed_shows:
        season_details = get_season_details_from_trakt(show.trakt_id, show.current_season)
        if season_details['aired_episodes'] > show.episodes_processed:
            await tv_queue.put({'tmdb_id': show.tmdb_id, 'imdb_id': show.imdb_id, 'title': show.title, 'media_type': 'tv', 'season': show.current_season, 'episodes': list(range(show.episodes_processed + 1, season_details['aired_episodes'] + 1))})
```

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

### Control Processing Queues - Skip and Clear (TypeScript)

Source: https://context7.com/woahai321/seerrbridge/llms.txt

Manages movie and TV show processing queues by allowing users to skip individual items or clear entire queues. It utilizes API calls for frontend interactions and database updates for backend operations. Dependencies include API communication modules and UI feedback components (toasts).

```typescript
// Frontend: Queue management composable (composables/useQueueManagement.ts)
import { useApi } from './useApi'
import { useToast } from './useToast'

export const useQueueManagement = () => {
  const { apiCall } = useApi()
  const { showToast } = useToast()

  // Skip a specific item in the queue
  const skipItem = async (tmdbId: number, mediaType: 'movie' | 'tv') => {
    try {
      const response = await apiCall('/api/queue/skip-item', {
        method: 'POST',
        body: { tmdb_id: tmdbId, media_type: mediaType }
      })

      if (response.success) {
        showToast('Item skipped successfully', 'success')
      }
      return response
    } catch (error) {
      showToast('Failed to skip item', 'error')
      throw error
    }
  }

  // Clear entire queue by media type
  const clearQueue = async (mediaType: 'movie' | 'tv' | 'all') => {
    try {
      const response = await apiCall('/api/queue/clear', {
        method: 'POST',
        body: { media_type: mediaType }
      })

      showToast(`Queue cleared: ${response.cleared_count} items`, 'success')
      return response
    } catch (error) {
      showToast('Failed to clear queue', 'error')
      throw error
    }
  }

  return { skipItem, clearQueue }
}

// Usage in Vue component
const { skipItem, clearQueue } = useQueueManagement()

// Skip a single movie
await skipItem(12345, 'movie')

// Clear all TV show queue
await clearQueue('tv')

// Backend: Queue skip handler (server/api/queue/skip-item.post.ts)
export default defineEventHandler(async (event) => {
  const { tmdb_id, media_type } = await readBody(event)

  const db = await getDatabaseConnection()

  // Update media status to 'cancelled'
  await db.execute(`
    UPDATE unified_media
    SET status = 'cancelled',
        is_in_queue = 0,
        updated_at = NOW()
    WHERE tmdb_id = ? AND media_type = ?
  `, [tmdb_id, media_type])

  // Add to cancellation registry (prevents processing)
  cancellationRegistry.add(`${tmdb_id}_${media_type}`)

  return { success: true, message: 'Item cancelled' }
})
```

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

### POST /jellyseer-webhook/

Source: https://context7.com/woahai321/seerrbridge/llms.txt

Endpoint for receiving automated media request notifications from Overseerr or Jellyseerr to trigger the ingestion and queueing process.

```APIDOC
## POST /jellyseer-webhook/

### Description
Receives webhook notifications from Overseerr/Jellyseerr when media is requested. This triggers metadata enrichment via Trakt and adds the item to the internal processing queue.

### Method
POST

### Endpoint
/jellyseer-webhook/

### Request Body
- **notification_type** (string) - Required - The type of notification sent.
- **media** (object) - Required - Object containing media details.
  - **media_type** (string) - Required - 'movie' or 'tv'.
  - **tmdbId** (integer) - Required - The TMDB ID of the requested media.
- **request** (object) - Required - Object containing request identification details.
  - **request_id** (integer) - Required - The internal Overseerr request ID.

### Request Example
{
    "notification_type": "request",
    "media": {
        "media_type": "movie",
        "tmdbId": 12345
    },
    "request": {
        "request_id": 1
    }
}

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successfully queued.
- **message** (string) - A confirmation message.

#### Response Example
{
    "success": true,
    "message": "Request added to queue"
}
```

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

### Overseerr API Client

Source: https://context7.com/woahai321/seerrbridge/llms.txt

This section details the Python client for the Overseerr API, including functions to fetch approved media requests and aggregate TV show requests.

```APIDOC
## GET /api/v1/request

### Description
Fetches all approved media requests from Overseerr. It aggregates TV show requests that span multiple seasons into a single entry.

### Method
GET

### Endpoint
/api/v1/request

### Query Parameters
- **take** (integer) - Optional - The maximum number of requests to return.
- **filter** (string) - Optional - Filters requests by status (e.g., 'approved').
- **sort** (string) - Optional - Sorts requests by a specified field (e.g., 'added').

### Request Body
None

### Response
#### Success Response (200)
- **results** (array) - A list of media requests. Each item contains details about the requested media, including its ID, type, and potentially seasons for TV shows. TV shows with multiple season requests will be aggregated.

#### Response Example
```json
{
  "pageInfo": {
    "page": 1,
    "pageSize": 50,
    "count": 1,
    "nextOffset": 50
  },
  "results": [
    {
      "id": 1,
      "movieId": null,
      "tvShowId": 12345,
      "seasons": [
        {
          "seasonNumber": 1
        },
        {
          "seasonNumber": 2
        }
      ],
      "media": {
        "tmdbId": 12345,
        "tvdbId": null,
        "imdbId": null,
        "tmdbCollectionId": null,
        "tmdbSeriesId": 12345,
        "malId": null,
        "doubanId": null,
        "imdbSeasonId": null,
        "year": 2023,
        "mediaType": "tv",
        "posterPath": "/path/to/poster.jpg",
        "name": "Sample TV Show",
        "status": 3,
        "remoteId": "tt1234567"
      },
      "addedBy": {
        "id": 1,
        "username": "user1",
        "avatar": "/path/to/avatar.jpg"
      },
      "createdAt": "2023-10-27T10:00:00Z",
      "is4k": false,
      "isAvailable": true,
      "availableAt": "2023-10-27T10:00:00Z",
      "aggregated_request_ids": [1, 5]
    }
  ]
}
```

## POST /api/v1/request/{id}/complete

### Description
Marks a specific media request in Overseerr as completed.

### Method
POST

### Endpoint
/api/v1/request/{id}/complete

### Path Parameters
- **id** (integer) - Required - The ID of the request to mark as completed.

### Query Parameters
None

### Request Body
None

### Response
#### Success Response (200)
- Returns `true` if the request was successfully marked as completed.

#### Response Example
```json
true
```

#### Error Response (e.g., 404 Not Found, 400 Bad Request)
- Returns an error message detailing the issue.

```

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

### Retrieve Media Details from Trakt API

Source: https://context7.com/woahai321/seerrbridge/llms.txt

Fetches detailed media information from Trakt.tv using TMDB IDs. It implements a local database cache check to minimize API consumption and returns a structured dictionary of media metadata.

```python
def get_media_details_from_trakt(tmdb_id: str, media_type: str) -> dict:
    db = get_db()
    existing_media = db.query(UnifiedMedia).filter(UnifiedMedia.tmdb_id == int(tmdb_id)).first()
    if existing_media and existing_media.trakt_id:
        trakt_id = int(existing_media.trakt_id)
    else:
        trakt_type = 'show' if media_type == 'tv' else 'movie'
        url = f"https://api.trakt.tv/search/tmdb/{tmdb_id}?type={trakt_type}"
        headers = {"Content-type": "application/json", "trakt-api-key": TRAKT_API_KEY, "trakt-api-version": "2"}
        response = requests.get(url, headers=headers, timeout=10)
        response.raise_for_status()
        data = response.json()
        if not data: return None
        trakt_id = data[0][trakt_type]['ids']['trakt']
    
    trakt_type = 'shows' if media_type == 'tv' else 'movies'
    url = f"https://api.trakt.tv/{trakt_type}/{trakt_id}?extended=full"
    response = requests.get(url, headers=headers, timeout=10)
    media_data = response.json()
    return {'trakt_id': trakt_id, 'imdb_id': media_data['ids'].get('imdb'), 'title': media_data.get('title'), 'year': media_data.get('year'), 'overview': media_data.get('overview'), 'rating': media_data.get('rating'), 'genres': media_data.get('genres', []), 'status': media_data.get('status'), 'network': media_data.get('network'), 'aired_episodes': media_data.get('aired_episodes')}
```

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

### Asynchronous Media Processing Queue

Source: https://context7.com/woahai321/seerrbridge/llms.txt

Processes movie requests using browser automation while ensuring concurrency control via a semaphore. It handles queue items by searching for torrents and updating the internal database status accordingly.

```python
async def process_movie_queue():
    while True:
        try:
            item = await movie_queue.get()
            async with browser_semaphore:
                update_media_request_status(item['tmdb_id'], 'movie', 'processing', processing_stage='browser_automation')
                driver = get_driver()
                success = search_dmm(driver=driver, imdb_id=item['imdb_id'], title=item['title'], media_type='movie', size_limit=MAX_MOVIE_SIZE)
                if success:
                    update_media_request_status(item['tmdb_id'], 'movie', 'completed')
                    log_success(f"Movie completed: {item['title']}")
                else:
                    mark_media_failed(item['tmdb_id'], 'movie', 'No suitable torrents found')
            movie_queue.task_done()
        except Exception as e:
            logger.error(f"Error processing movie queue: {e}")
            movie_queue.task_done()
```

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

### Implement Overseerr Webhook Handler in FastAPI

Source: https://context7.com/woahai321/seerrbridge/llms.txt

This endpoint receives JSON notifications from Overseerr/Jellyseerr. It extracts media metadata, fetches additional details via Trakt, persists the request in the database, and adds the task to the appropriate processing queue.

```python
from fastapi import FastAPI, Request
from seerr.trakt import get_media_details_from_trakt
from seerr.unified_media_manager import track_media_request
from seerr.background_tasks import movie_queue, tv_queue

@app.post("/jellyseer-webhook/")
async def jellyseer_webhook(request: Request):
    data = await request.json()

    # Extract media information
    media = data.get('media', {})
    tmdb_id = media.get('tmdbId')
    media_type = media.get('media_type')  # 'movie' or 'tv'
    request_id = data.get('request', {}).get('request_id')

    # Fetch enriched metadata from Trakt
    media_details = get_media_details_from_trakt(str(tmdb_id), media_type)

    # Track in database (creates UnifiedMedia record)
    track_media_request(
        tmdb_id=tmdb_id,
        imdb_id=media_details.get('imdb_id'),
        media_type=media_type,
        title=media_details.get('title'),
        year=media_details.get('year'),
        overseerr_request_id=request_id,
        status='pending'
    )

    # Add to appropriate queue
    queue = tv_queue if media_type == 'tv' else movie_queue
    await queue.put({
        'tmdb_id': tmdb_id,
        'imdb_id': media_details.get('imdb_id'),
        'title': media_details.get('title'),
        'media_type': media_type
    })

    return {"success": True, "message": "Request added to queue"}
```

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

### Aggregate Overseerr TV Requests

Source: https://context7.com/woahai321/seerrbridge/llms.txt

Fetches approved media requests from the Overseerr API and groups multiple requests for the same TV show into a single record. This ensures that fragmented season requests are processed as a unified object.

```python
import requests
from seerr.config import OVERSEERR_API_BASE_URL, OVERSEERR_API_KEY

def get_overseerr_media_requests() -> list[dict]:
    url = f"{OVERSEERR_API_BASE_URL}/api/v1/request?take=500&filter=approved&sort=added"
    headers = {"X-Api-Key": OVERSEERR_API_KEY, "Content-Type": "application/json"}
    response = requests.get(url, headers=headers, timeout=10)
    response.raise_for_status()
    return aggregate_tv_requests_by_media_id(response.json().get('results', []))

def aggregate_tv_requests_by_media_id(requests: list[dict]) -> list[dict]:
    media_groups = {}
    for request in requests:
        media_id = request['media']['id']
        if request['media']['mediaType'] == 'tv':
            media_groups.setdefault(media_id, []).append(request)
        else:
            media_groups[f"movie_{request['id']}"] = [request]
    
    aggregated = []
    for group in media_groups.values():
        if len(group) == 1: aggregated.append(group[0])
        else:
            base = group[0].copy()
            all_seasons = []
            all_ids = []
            for req in group:
                all_ids.append(req['id'])
                for s in req.get('seasons', []):
                    if not any(x['seasonNumber'] == s['seasonNumber'] for x in all_seasons):
                        all_seasons.append(s)
            base['seasons'] = sorted(all_seasons, key=lambda x: x['seasonNumber'])
            base['aggregated_request_ids'] = all_ids
            aggregated.append(base)
    return aggregated
```

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

### POST /api/queue/clear - Clear Processing Queue

Source: https://context7.com/woahai321/seerrbridge/llms.txt

Clears all items from a specified processing queue (movie, TV, or all).

```APIDOC
## POST /api/queue/clear

### Description
Clears all items from a specified processing queue (movie, TV, or all).

### Method
POST

### Endpoint
/api/queue/clear

### Parameters
#### Request Body
- **media_type** (string) - Required - The type of media queue to clear ('movie', 'tv', or 'all').

### Request Example
```json
{
  "media_type": "tv"
}
```

### Response
#### Success Response (200)
- **cleared_count** (integer) - The number of items cleared from the queue.

#### Response Example
```json
{
  "cleared_count": 50
}
```
```

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

### POST /api/queue/skip-item - Skip Queue Item

Source: https://context7.com/woahai321/seerrbridge/llms.txt

Skips a specific item in the processing queue by marking it as cancelled.

```APIDOC
## POST /api/queue/skip-item

### Description
Skips a specific item in the processing queue by marking it as cancelled and adding it to a cancellation registry.

### Method
POST

### Endpoint
/api/queue/skip-item

### Parameters
#### Request Body
- **tmdb_id** (integer) - Required - The TMDB ID of the media item.
- **media_type** (string) - Required - The type of media ('movie' or 'tv').

### Request Example
```json
{
  "tmdb_id": 12345,
  "media_type": "movie"
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the item was successfully skipped.
- **message** (string) - A confirmation message.

#### Response Example
```json
{
  "success": true,
  "message": "Item cancelled"
}
```
```

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

### Fetch TV Season Metadata from Trakt

Source: https://context7.com/woahai321/seerrbridge/llms.txt

Retrieves specific season-level data for a given Trakt show ID, including episode counts and aired counts. This function requires a valid Trakt show ID and season number as inputs.

```python
def get_season_details_from_trakt(trakt_show_id: str, season_number: int) -> dict:
    url = f"https://api.trakt.tv/shows/{trakt_show_id}/seasons/{season_number}?extended=full"
    headers = {"Content-type": "application/json", "trakt-api-key": TRAKT_API_KEY, "trakt-api-version": "2"}
    response = requests.get(url, headers=headers, timeout=10)
    response.raise_for_status()
    season_data = response.json()
    return {'season_number': season_number, 'episode_count': season_data.get('episode_count', 0), 'aired_episodes': season_data.get('aired_episodes', 0), 'title': season_data.get('title'), 'overview': season_data.get('overview')}
```
Tokens:
Raw