API Reference - Kuschel-code/JellyfinUpscalerPlugin GitHub Wiki

📊 API Reference - Developer Documentation

Complete API documentation for developers and advanced users

🚀 Getting Started

Plugin API Access

The Jellyfin AI Upscaler Plugin provides a comprehensive JavaScript API for developers:

// Access the main plugin API
const upscaler = window.jellyfinUpscalerAPI;

// Check if plugin is available
if (upscaler && upscaler.isReady()) {
    console.log('🔥 AI Upscaler API ready!');
}

Authentication

// API uses Jellyfin's authentication automatically
const apiClient = window.ApiClient;
const upscalerAPI = new JellyfinUpscalerAPI(apiClient);

🎯 Core API Methods

Settings Management

`getSettings()`

Get current plugin settings.

const settings = await upscaler.getSettings();
console.log(settings);
// Returns:
{
  "ai_method": "DLSS 3.0",
  "scale_factor": 2.0,
  "quality_preset": "high",
  "language": "en",
  // ... more settings
}

`updateSettings(newSettings)`

Update plugin settings.

await upscaler.updateSettings({
  ai_method: "FSR 3.0",
  scale_factor: 2.5,
  hdr_enhancement: true
});

`resetSettings()`

Reset to default settings.

await upscaler.resetSettings();

Hardware Detection

`getHardwareInfo()`

Get detailed hardware information.

const hardware = await upscaler.getHardwareInfo();
console.log(hardware);
// Returns:
{
  "gpu": {
    "vendor": "NVIDIA",
    "model": "RTX 4080",
    "vram": 16384,
    "driver": "536.23",
    "compute_capability": "8.9"
  },
  "cpu": {
    "model": "Intel i7-12700K",
    "cores": 12,
    "threads": 20
  },
  "system": {
    "os": "Windows 11",
    "ram": 32768,
    "platform": "x64"
  }
}

`getSupportedMethods()`

Get AI methods supported by current hardware.

const methods = await upscaler.getSupportedMethods();
// Returns: ["DLSS 3.0", "DLSS 2.4", "FSR 3.0", "XeSS", ...]

Performance Monitoring

`getPerformanceStats()`

Get real-time performance statistics.

const stats = await upscaler.getPerformanceStats();
console.log(stats);
// Returns:
{
  "fps": 58.5,
  "frame_time": 17.1,
  "gpu_usage": 75,
  "vram_usage": 6.2,
  "temperature": 68,
  "power_usage": 320,
  "upscale_time": 4.2,
  "quality_score": 8.7
}

`startPerformanceMonitoring(callback, interval)`

Start continuous performance monitoring.

upscaler.startPerformanceMonitoring((stats) => {
  console.log('Performance update:', stats);
}, 1000); // Update every second

`stopPerformanceMonitoring()`

Stop performance monitoring.

upscaler.stopPerformanceMonitoring();

🎬 Video Processing API

Manual Processing

`processVideo(videoElement, options)`

Manually apply upscaling to a video element.

const video = document.querySelector('video');
const options = {
  ai_method: 'DLSS 3.0',
  scale_factor: 2.0,
  hdr_enhancement: true,
  real_time: true
};

await upscaler.processVideo(video, options);

`stopProcessing(videoElement)`

Stop processing a video.

await upscaler.stopProcessing(video);

Batch Processing

`processVideoFile(filePath, outputPath, options)`

Process a video file (server-side).

const result = await upscaler.processVideoFile(
  '/media/movies/input.mp4',
  '/media/movies/upscaled.mp4',
  {
    ai_method: 'Real-ESRGAN',
    scale_factor: 4.0,
    quality: 'ultra'
  }
);

`getProcessingQueue()`

Get current processing queue.

const queue = await upscaler.getProcessingQueue();
// Returns array of processing jobs

🎨 Effects & Filters API

Custom Effects

`addCustomEffect(name, shader)`

Add a custom shader effect.

const shaderCode = `
  precision mediump float;
  uniform sampler2D u_image;
  varying vec2 v_texCoord;
  
  void main() {
    vec4 color = texture2D(u_image, v_texCoord);
    color.rgb = pow(color.rgb, vec3(1.0/2.2)); // Gamma correction
    gl_FragColor = color;
  }
`;

upscaler.addCustomEffect('gamma_correct', shaderCode);

`applyEffect(videoElement, effectName, parameters)`

Apply a custom effect.

await upscaler.applyEffect(video, 'gamma_correct', {
  gamma: 2.2,
  intensity: 0.8
});

Built-in Effects

`applySharpening(videoElement, strength)`

Apply sharpening filter.

await upscaler.applySharpening(video, 0.7);

`applyColorEnhancement(videoElement, options)`

Apply color enhancement.

await upscaler.applyColorEnhancement(video, {
  saturation: 1.2,
  contrast: 1.1,
  brightness: 0.05,
  hue_shift: 2
});

🔧 Configuration API

Profile Management

`createProfile(name, settings)`

Create a custom settings profile.

const profile = {
  name: "4K Gaming",
  settings: {
    ai_method: "DLSS 3.0",
    scale_factor: 1.5,
    quality_preset: "performance",
    frame_interpolation: false,
    thermal_limit: 75
  },
  conditions: {
    resolution: ">=1440p",
    content_type: "game",
    gpu_vram: ">=8GB"
  }
};

await upscaler.createProfile(profile);

`getProfiles()`

Get all available profiles.

const profiles = await upscaler.getProfiles();

`applyProfile(name)`

Apply a specific profile.

await upscaler.applyProfile("4K Gaming");

Auto-Detection

`enableAutoDetection(options)`

Enable automatic content detection and optimization.

upscaler.enableAutoDetection({
  content_analysis: true,
  hardware_optimization: true,
  adaptive_quality: true,
  learning_mode: true
});

📱 Event System

Event Listeners

Standard Events

// Settings changed
upscaler.on('settings.changed', (newSettings) => {
  console.log('Settings updated:', newSettings);
});

// Processing started
upscaler.on('processing.started', (videoInfo) => {
  console.log('Started processing:', videoInfo);
});

// Processing completed
upscaler.on('processing.completed', (result) => {
  console.log('Processing completed:', result);
});

// Error occurred
upscaler.on('error', (error) => {
  console.error('Upscaler error:', error);
});

// Performance update
upscaler.on('performance.update', (stats) => {
  updatePerformanceUI(stats);
});

Custom Events

// Register custom event
upscaler.on('custom.quality_threshold_reached', (data) => {
  console.log('Quality threshold reached:', data);
});

// Emit custom event
upscaler.emit('custom.user_action', { action: 'manual_enhance' });

🛠️ Utility Functions

Format Conversion

`convertToWebGL(imageData)`

Convert image data to WebGL texture.

const texture = upscaler.convertToWebGL(imageData);

`convertToCanvas(texture)`

Convert WebGL texture to canvas.

const canvas = upscaler.convertToCanvas(texture);

Quality Assessment

`calculatePSNR(original, enhanced)`

Calculate PSNR between two images.

const psnr = upscaler.calculatePSNR(originalImage, enhancedImage);
console.log('PSNR:', psnr, 'dB');

`calculateSSIM(original, enhanced)`

Calculate SSIM between two images.

const ssim = upscaler.calculateSSIM(originalImage, enhancedImage);
console.log('SSIM:', ssim);

🔍 Advanced Features

Model Management

`loadCustomModel(modelPath, config)`

Load a custom AI model.

const model = await upscaler.loadCustomModel(
  '/models/custom_anime_4x.onnx',
  {
    input_size: [3, 224, 224],
    output_size: [3, 896, 896],
    scale_factor: 4,
    model_type: 'anime'
  }
);

`unloadModel(modelId)`

Unload a model from memory.

await upscaler.unloadModel('custom_anime_4x');

GPU Compute

`executeComputeShader(shaderCode, inputs, outputs)`

Execute custom compute shader.

const outputs = await upscaler.executeComputeShader(
  computeShaderCode,
  { input_texture: texture },
  { output_texture: 'rgba32f' }
);

📊 Data Export/Import

Settings Export

`exportSettings(format)`

Export current settings.

// JSON format
const jsonSettings = await upscaler.exportSettings('json');

// Configuration file format
const configFile = await upscaler.exportSettings('config');

`importSettings(data, format)`

Import settings from data.

await upscaler.importSettings(settingsData, 'json');

Performance Data

`exportPerformanceData(options)`

Export performance statistics.

const perfData = await upscaler.exportPerformanceData({
  format: 'csv',
  timeRange: '24h',
  includeSystemInfo: true,
  aggregation: 'hourly'
});

🔐 Security & Permissions

API Key Management

// Set API key for advanced features
upscaler.setAPIKey('your-api-key-here');

// Check permissions
const permissions = await upscaler.getPermissions();
console.log('Available permissions:', permissions);

Content Security

// Enable content verification
upscaler.enableContentVerification({
  checkIntegrity: true,
  validateSource: true,
  logAccess: true
});

🧪 Testing & Debugging

Debug Mode

// Enable debug mode
upscaler.setDebugMode(true);

// Get debug information
const debugInfo = await upscaler.getDebugInfo();

Testing Utilities

// Run built-in tests
const testResults = await upscaler.runTests();

// Benchmark performance
const benchmark = await upscaler.benchmark({
  duration: 30,
  methods: ['DLSS 3.0', 'FSR 3.0'],
  resolutions: ['1080p', '1440p']
});

📋 API Response Formats

Standard Response

{
  "success": true,
  "data": { ... },
  "message": "Operation completed successfully",
  "timestamp": "2024-06-21T15:30:00Z",
  "version": "1.3.0"
}

Error Response

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_VRAM",
    "message": "Not enough VRAM for 4K upscaling",
    "details": {
      "required": 8192,
      "available": 4096
    }
  },
  "timestamp": "2024-06-21T15:30:00Z"
}

📚 Code Examples

Complete Integration Example

class MyUpscalerIntegration {
  constructor() {
    this.upscaler = window.jellyfinUpscalerAPI;
    this.init();
  }

  async init() {
    // Wait for API to be ready
    await this.upscaler.waitForReady();
    
    // Get hardware info
    const hardware = await this.upscaler.getHardwareInfo();
    console.log('Hardware:', hardware);
    
    // Set up event listeners
    this.upscaler.on('processing.completed', this.onProcessingComplete.bind(this));
    
    // Start performance monitoring
    this.upscaler.startPerformanceMonitoring(this.onPerformanceUpdate.bind(this), 1000);
  }

  async enhanceVideo(videoElement) {
    const options = {
      ai_method: 'DLSS 3.0',
      scale_factor: 2.0,
      hdr_enhancement: true
    };
    
    return await this.upscaler.processVideo(videoElement, options);
  }

  onProcessingComplete(result) {
    console.log('Video enhancement completed:', result);
  }

  onPerformanceUpdate(stats) {
    this.updateUI(stats);
  }
}

// Usage
const integration = new MyUpscalerIntegration();

🔗 Related Documentation

Installation Guide - Plugin installation
Configuration - Settings and options
Usage Guide - User interface guide
Performance - Optimization tips
Troubleshooting - Common issues

🚀 Ready to build with our API? Check out more examples in our GitHub repository!