metastar/metamesh-plugin-tmdb
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

initial commit

Browse Source
This commit is contained in:
Pierre
2026-01-10 15:33:36 +01:00
commit 2a740d2488
10 changed files with 763 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/workflows/docker.yml
+56
View File
@@ -0,0 +1,56 @@
name: Build and Push Docker Image
on:
push:
branches: [main, master]
tags: ['v*']
pull_request:
branches: [main, master]
env:
REGISTRY: ghcr.io
IMAGE_NAME: ${{ github.repository }}
jobs:
build:
runs-on: ubuntu-latest
permissions:
contents: read
packages: write
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3
- name: Log in to Container Registry
if: github.event_name != 'pull_request'
uses: docker/login-action@v3
with:
registry: ${{ env.REGISTRY }}
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
- name: Extract metadata
id: meta
uses: docker/metadata-action@v5
with:
images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
tags: |
type=ref,event=branch
type=ref,event=pr
type=semver,pattern={{version}}
type=semver,pattern={{major}}.{{minor}}
type=sha
- name: Build and push
uses: docker/build-push-action@v5
with:
context: .
push: ${{ github.event_name != 'pull_request' }}
tags: ${{ steps.meta.outputs.tags }}
labels: ${{ steps.meta.outputs.labels }}
cache-from: type=gha
cache-to: type=gha,mode=max
.gitignore
+5
View File
@@ -0,0 +1,5 @@
node_modules/
dist/
*.log
.env
.DS_Store
Dockerfile
+16
View File
@@ -0,0 +1,16 @@
FROM node:20-slim AS builder
WORKDIR /app
COPY package.json tsconfig.json ./
RUN npm install
COPY src/ ./src/
RUN npm run build
FROM node:20-slim
WORKDIR /app
COPY package.json ./
RUN npm install --omit=dev
COPY --from=builder /app/dist ./dist
EXPOSE 8080
HEALTHCHECK --interval=30s --timeout=5s --start-period=5s --retries=3 \
CMD node -e "require('http').get('http://localhost:8080/health', (r) => process.exit(r.statusCode === 200 ? 0 : 1))"
CMD ["node", "dist/index.js"]
README.md
+80
View File
@@ -0,0 +1,80 @@
# MetaMesh Plugin: TMDB
A MetaMesh plugin that fetches metadata from The Movie Database (TMDB) API.
## Description
This plugin enriches video metadata by querying the TMDB API:
- **Search by IMDB ID**: Uses existing IMDB ID for precise matching
- **Search by title**: Falls back to title/year search
- **Image download**: Downloads poster and backdrop images to `/files/poster/`
- **Rich metadata**: Fetches plot, rating, genres, studios
**Note**: This runs on the background queue as it makes external API calls.
## Metadata Fields
| Field | Description |
|-------|-------------|
| `tmdbid` | TMDB ID |
| `imdbid` | IMDB ID |
| `title` | Localized title |
| `originalTitle` | Original title |
| `movieYear` | Release year |
| `releasedate` | Full release date |
| `rating` | Vote average |
| `plot/eng` | English plot synopsis |
| `poster` | Poster image CID |
| `posterPath` | Poster file path |
| `backdrop` | Backdrop image CID |
| `backdropPath` | Backdrop file path |
| `genres` | Genre set |
| `studio` | Production company set |
## Dependencies
- Requires `file-info`, `filename-parser`, and `jellyfin-nfo` plugins
## Configuration
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `apiKey` | string | Yes | TMDB API key or v4 bearer token |
| `language` | select | No | Metadata language (default: en-US) |
## API Endpoints
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/health` | GET | Health check |
| `/manifest` | GET | Plugin manifest |
| `/configure` | POST | Update configuration (API key) |
| `/process` | POST | Process a file |
## Running Locally
```bash
npm install
npm run build
npm start
```
## Docker
```bash
docker build -t metamesh-plugin-tmdb .
docker run -p 8080:8080 metamesh-plugin-tmdb
```
## Environment Variables
| Variable | Default | Description |
|----------|---------|-------------|
| `PORT` | `8080` | HTTP server port |
| `HOST` | `0.0.0.0` | HTTP server host |
| `FILES_PATH` | `/files` | Base path for image downloads |
## License
MIT
package.json
+10
View File
@@ -0,0 +1,10 @@
{
"name": "@metazla/plugin-tmdb",
"version": "1.0.0",
"description": "MetaMesh plugin: Fetches metadata from TMDB API",
"type": "module",
"main": "dist/index.js",
"scripts": { "build": "tsc", "start": "node dist/index.js" },
"dependencies": { "fastify": "^5.0.0", "axios": "^1.6.0" },
"devDependencies": { "@types/node": "^20.0.0", "typescript": "^5.3.0" }
}
src/index.ts
+33
View File
@@ -0,0 +1,33 @@
import Fastify from 'fastify';
import type { HealthResponse, ProcessRequest, ProcessResponse, CallbackPayload, ConfigureRequest, ConfigureResponse } from './types.js';
import { manifest, process as processFile, configure } from './plugin.js';
const app = Fastify({ logger: true });
let ready = false;
app.get('/health', async (): Promise<HealthResponse> => ({ status: 'healthy', ready, version: manifest.version }));
app.get('/manifest', async () => manifest);
app.post<{ Body: ConfigureRequest }>('/configure', async (request): Promise<ConfigureResponse> => {
try {
configure(request.body.config || {});
console.log(`[${manifest.id}] Configuration updated`);
return { status: 'ok' };
} catch (error) {
return { status: 'error', error: error instanceof Error ? error.message : String(error) };
}
});
app.post<{ Body: ProcessRequest }>('/process', async (request, reply) => {
const { taskId, cid, filePath, callbackUrl, metaCoreUrl } = request.body;
if (!taskId || !cid || !filePath || !callbackUrl || !metaCoreUrl) {
return reply.send({ status: 'rejected', error: 'Missing required fields' } as ProcessResponse);
}
processFile(request.body, async (payload: CallbackPayload) => {
try { await fetch(callbackUrl, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(payload) }); }
catch (error) { console.error(`[${manifest.id}] Callback error:`, error); }
}).catch(console.error);
return reply.send({ status: 'accepted' } as ProcessResponse);
});
const port = parseInt(process.env.PORT || '8080', 10);
app.listen({ port, host: '0.0.0.0' }).then(() => { ready = true; console.log(`[${manifest.id}] Listening on port ${port}`); });
process.on('SIGTERM', async () => { ready = false; await app.close(); process.exit(0); });
src/meta-core-client.ts
+89
View File
@@ -0,0 +1,89 @@
/**
* meta-core API Client for writing metadata
* Fails gracefully if meta-core is unavailable (logs warning, returns without throwing)
*/
export class MetaCoreClient {
constructor(private baseUrl: string) {}
private async safeFetch(url: string, options: RequestInit): Promise<Response | null> {
try {
return await fetch(url, { ...options, signal: AbortSignal.timeout(5000) });
} catch (error) {
console.warn(`[MetaCoreClient] Warning: meta-core unavailable at ${this.baseUrl}`);
return null;
}
}
async setProperty(hashId: string, key: string, value: string): Promise<void> {
const response = await this.safeFetch(`${this.baseUrl}/meta/${hashId}/${key}`, {
method: 'PUT',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ value }),
});
if (response && !response.ok) {
console.warn(`[MetaCoreClient] Failed to set property: ${response.status}`);
}
}
async getProperty(hashId: string, key: string): Promise<string | null> {
const response = await this.safeFetch(`${this.baseUrl}/meta/${hashId}/${key}`, { method: 'GET' });
if (!response || response.status === 404) return null;
if (!response.ok) return null;
const data = await response.json() as { value?: string };
return data.value ?? null;
}
async mergeMetadata(hashId: string, metadata: Record<string, string>): Promise<void> {
const response = await this.safeFetch(`${this.baseUrl}/meta/${hashId}`, {
method: 'PATCH',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(metadata),
});
if (response && !response.ok) {
console.warn(`[MetaCoreClient] Failed to merge metadata: ${response.status}`);
}
}
async deleteProperty(hashId: string, key: string): Promise<void> {
const response = await this.safeFetch(`${this.baseUrl}/meta/${hashId}/${key}`, { method: 'DELETE' });
if (response && !response.ok && response.status !== 404) {
console.warn(`[MetaCoreClient] Failed to delete property: ${response.status}`);
}
}
async addToSet(hashId: string, key: string, value: string): Promise<void> {
const response = await this.safeFetch(`${this.baseUrl}/meta/${hashId}/_add/${key}`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ value }),
});
if (response && !response.ok) {
console.warn(`[MetaCoreClient] Failed to add to set: ${response.status}`);
}
}
async getMetadata(hashId: string): Promise<Record<string, string>> {
const response = await this.safeFetch(`${this.baseUrl}/meta/${hashId}`, { method: 'GET' });
if (!response || response.status === 404) return {};
if (!response.ok) return {};
const data = await response.json() as { metadata?: Record<string, string> };
return data.metadata ?? {};
}
/**
* Compute CID for a file
* @param path - Path relative to FILES_PATH (e.g., "poster/Movie (2024)[tmdb12345]_poster.jpg")
* @returns CID string or null if failed
*/
async computeFileCID(path: string): Promise<string | null> {
const response = await this.safeFetch(`${this.baseUrl}/file/cid`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ path }),
});
if (!response || !response.ok) return null;
const data = await response.json() as { cid?: string };
return data.cid ?? null;
}
}
src/plugin.ts
+386
View File
@@ -0,0 +1,386 @@
/**
* TMDB Plugin
* Fetches metadata from The Movie Database API
* Downloads poster and backdrop images to /files/poster/
*/
import axios from 'axios';
import * as fs from 'fs/promises';
import { createWriteStream, existsSync, mkdirSync } from 'fs';
import * as path from 'path';
import { pipeline } from 'stream/promises';
import type { PluginManifest, ProcessRequest, CallbackPayload } from './types.js';
import { MetaCoreClient } from './meta-core-client.js';
const IMAGE_BASE_URL = 'https://image.tmdb.org/t/p/original';
// Use globalThis.process to avoid conflict with the exported process function
const FILES_PATH = (globalThis as any).process?.env?.FILES_PATH || '/files';
export const manifest: PluginManifest = {
id: 'tmdb',
name: 'TMDB Metadata',
version: '1.0.0',
description: 'Fetches metadata from The Movie Database (TMDB) API',
author: 'MetaMesh',
dependencies: ['file-info', 'filename-parser', 'jellyfin-nfo'],
priority: 30,
color: '#01B4E4',
defaultQueue: 'background',
timeout: 60000,
schema: {
tmdbid: { label: 'TMDB ID', type: 'string', readonly: true },
imdbid: { label: 'IMDB ID', type: 'string' },
originalTitle: { label: 'Original Title', type: 'string' },
movieYear: { label: 'Release Year', type: 'number' },
releasedate: { label: 'Release Date', type: 'string' },
rating: { label: 'Vote Average', type: 'string', readonly: true },
'plot/eng': { label: 'Plot (English)', type: 'string', readonly: true },
},
config: {
apiKey: {
type: 'string',
label: 'TMDB API Key or Bearer Token',
required: true,
secret: true,
},
language: {
type: 'select',
label: 'Metadata Language',
default: 'en-US',
},
},
};
const BASE_URL = 'https://api.themoviedb.org/3';
let apiKey: string | null = null;
let isV4Token = false;
let metadataLanguage = 'en-US';
export function configure(config: Record<string, unknown>): void {
console.log(`[tmdb] Received config keys: ${Object.keys(config).join(', ')}`);
apiKey = config.apiKey as string || null;
if (apiKey) {
isV4Token = apiKey.startsWith('eyJ');
console.log(`[tmdb] API key configured (type: ${isV4Token ? 'v4 token' : 'v3 key'}, length: ${apiKey.length})`);
} else {
console.log(`[tmdb] WARNING: No API key in config`);
}
const lang = config.language as string || 'en';
metadataLanguage = lang.includes('-') ? lang : `${lang}-${lang.toUpperCase()}`;
if (metadataLanguage === 'en-en') metadataLanguage = 'en-US';
console.log(`[tmdb] Language set to: ${metadataLanguage}`);
}
function getAxiosConfig(params: Record<string, string> = {}) {
if (isV4Token) {
return {
headers: { Authorization: `Bearer ${apiKey}`, 'Content-Type': 'application/json' },
params,
};
}
return { params: { api_key: apiKey, ...params } };
}
async function findByImdbId(imdbId: string): Promise<any> {
try {
const config = getAxiosConfig({ language: metadataLanguage, external_source: 'imdb_id' });
const response = await axios.get(`${BASE_URL}/find/${imdbId}`, config);
const result = response.data.movie_results?.[0] || response.data.tv_results?.[0];
if (result) {
const mediaType = response.data.movie_results?.[0] ? 'movie' : 'tv';
return getByTmdbId(result.id.toString(), mediaType);
}
} catch {
return null;
}
return null;
}
async function getByTmdbId(tmdbId: string, mediaType: string): Promise<any> {
try {
const config = getAxiosConfig({ language: metadataLanguage });
const response = await axios.get(`${BASE_URL}/${mediaType}/${tmdbId}`, config);
return response.data;
} catch {
return null;
}
}
async function searchByTitle(title: string, year?: string, videoType?: string): Promise<any> {
try {
const mediaType = videoType === 'tvshow' || videoType === 'tv' ? 'tv' : 'movie';
const endpoint = `search/${mediaType}`;
const params: Record<string, string> = { language: metadataLanguage, query: title };
if (year) params.year = year;
const config = getAxiosConfig(params);
const response = await axios.get(`${BASE_URL}/${endpoint}`, config);
const results = response.data.results || [];
if (results.length > 0) {
return getByTmdbId(results[0].id.toString(), mediaType);
}
} catch {
return null;
}
return null;
}
/**
* Sanitize filename by removing invalid characters
*/
function sanitizeFilename(name: string): string {
return name
.replace(/[<>:"/\\|?*]/g, '') // Remove invalid chars
.replace(/\s+/g, ' ') // Normalize whitespace
.trim();
}
/**
* Download an image from URL to local path
*/
async function downloadImage(imageUrl: string, localPath: string): Promise<boolean> {
try {
const response = await axios({
method: 'get',
url: imageUrl,
responseType: 'stream',
timeout: 30000,
});
// Ensure directory exists
const dir = path.dirname(localPath);
if (!existsSync(dir)) {
mkdirSync(dir, { recursive: true });
}
// Pipe the response to a file
const writer = createWriteStream(localPath);
await pipeline(response.data, writer);
console.log(`[tmdb] Downloaded image to ${localPath}`);
return true;
} catch (error) {
console.error(`[tmdb] Failed to download image from ${imageUrl}: ${error instanceof Error ? error.message : String(error)}`);
return false;
}
}
/**
* Download and hash an image, returning its CID and path
* @returns {Promise<{cid: string, path: string} | null>}
*/
async function downloadAndHashImage(
imagePath: string,
imageType: string,
title: string,
year: string | undefined,
tmdbId: string,
metaCore: MetaCoreClient
): Promise<{ cid: string; path: string } | null> {
if (!imagePath) {
return null;
}
const imageUrl = `${IMAGE_BASE_URL}${imagePath}`;
const ext = path.extname(imagePath) || '.jpg';
// Build filename: <title> (<year>)[tmdb<tmdbId>]_<type>.jpg
// Note: Don't include file CID to avoid duplicate posters for same movie
const safeName = sanitizeFilename(title);
const yearStr = year ? ` (${year})` : '';
const filename = `${safeName}${yearStr}[tmdb${tmdbId}]_${imageType}${ext}`;
const posterDir = path.join(FILES_PATH, 'poster');
const localPath = path.join(posterDir, filename);
// Relative path for storage (relative to filesPath)
const relativePath = `poster/${filename}`;
// Check if file already exists (skip download)
if (existsSync(localPath)) {
console.log(`[tmdb] Image already exists: ${localPath}`);
} else {
// Ensure poster directory exists
if (!existsSync(posterDir)) {
mkdirSync(posterDir, { recursive: true });
console.log(`[tmdb] Created poster directory: ${posterDir}`);
}
// Download the image
const downloaded = await downloadImage(imageUrl, localPath);
if (!downloaded) {
return null;
}
}
// Compute CID using meta-core API
try {
const cid = await metaCore.computeFileCID(relativePath);
if (cid) {
console.log(`[tmdb] Image ${imageType} CID: ${cid}`);
return { cid, path: relativePath };
} else {
console.warn(`[tmdb] Failed to compute CID for ${localPath}`);
}
} catch (e) {
console.error(`[tmdb] Failed to compute CID for ${localPath}: ${e instanceof Error ? e.message : String(e)}`);
}
return null;
}
export async function process(
request: ProcessRequest,
sendCallback: (payload: CallbackPayload) => Promise<void>
): Promise<void> {
const startTime = Date.now();
const metaCore = new MetaCoreClient(request.metaCoreUrl);
try {
const { cid, existingMeta } = request;
if (!apiKey) {
await sendCallback({
taskId: request.taskId,
status: 'skipped',
duration: Date.now() - startTime,
reason: 'No API key configured',
});
return;
}
if (existingMeta?.fileType !== 'video') {
await sendCallback({
taskId: request.taskId,
status: 'skipped',
duration: Date.now() - startTime,
reason: 'Not a video file',
});
return;
}
// Skip if already has TMDB data
if (existingMeta?.tmdbid) {
await sendCallback({
taskId: request.taskId,
status: 'skipped',
duration: Date.now() - startTime,
reason: 'Already has TMDB data',
});
return;
}
let tmdbData = null;
// Try by IMDB ID first
const imdbId = existingMeta?.imdbid;
if (imdbId) {
tmdbData = await findByImdbId(imdbId);
}
// Try by title search
if (!tmdbData) {
let title = existingMeta?.originalTitle || existingMeta?.fileName;
const year = existingMeta?.movieYear;
const videoType = existingMeta?.videoType;
// Strip trailing year from title if present (e.g., "Sintel 2010" -> "Sintel")
if (title && year) {
const yearRegex = new RegExp(`\\s*[\\(\\[]?${year}[\\)\\]]?\\s*$`);
title = title.replace(yearRegex, '').trim();
}
if (title) {
tmdbData = await searchByTitle(title, year, videoType);
}
}
if (tmdbData) {
const metadata: Record<string, string> = {};
const tmdbId = tmdbData.id ? String(tmdbData.id) : '';
if (tmdbId) metadata.tmdbid = tmdbId;
if (tmdbData.imdb_id) metadata.imdbid = tmdbData.imdb_id;
const originalTitle = tmdbData.original_title || tmdbData.original_name;
const localizedTitle = tmdbData.title || tmdbData.name;
if (localizedTitle) metadata.title = localizedTitle;
if (originalTitle) metadata.originalTitle = originalTitle;
const releaseDate = tmdbData.release_date || tmdbData.first_air_date;
let year: string | undefined;
if (releaseDate) {
metadata.releasedate = releaseDate;
year = releaseDate.split('-')[0];
if (year) {
metadata.movieYear = year;
}
}
if (tmdbData.overview) metadata['plot/eng'] = tmdbData.overview;
if (tmdbData.vote_average) metadata.rating = String(tmdbData.vote_average);
// Download and hash poster/backdrop images
const displayTitle = localizedTitle || originalTitle || 'Unknown';
if (tmdbData.poster_path && tmdbId) {
const posterResult = await downloadAndHashImage(
tmdbData.poster_path,
'poster',
displayTitle,
year,
tmdbId,
metaCore
);
if (posterResult) {
metadata.poster = posterResult.cid;
metadata.posterPath = posterResult.path;
console.log(`[tmdb] Set poster CID: ${posterResult.cid}`);
}
}
if (tmdbData.backdrop_path && tmdbId) {
const backdropResult = await downloadAndHashImage(
tmdbData.backdrop_path,
'backdrop',
displayTitle,
year,
tmdbId,
metaCore
);
if (backdropResult) {
metadata.backdrop = backdropResult.cid;
metadata.backdropPath = backdropResult.path;
console.log(`[tmdb] Set backdrop CID: ${backdropResult.cid}`);
}
}
await metaCore.mergeMetadata(cid, metadata);
// Add genres
for (const genre of tmdbData.genres || []) {
await metaCore.addToSet(cid, 'genres', genre.name);
}
// Add studios
for (const company of tmdbData.production_companies || []) {
await metaCore.addToSet(cid, 'studio', company.name);
}
await metaCore.addToSet(cid, 'tags', 'tmdb-verified');
}
await sendCallback({
taskId: request.taskId,
status: 'completed',
duration: Date.now() - startTime,
});
} catch (error) {
await sendCallback({
taskId: request.taskId,
status: 'failed',
duration: Date.now() - startTime,
error: error instanceof Error ? error.message : String(error),
});
}
}
src/types.ts
+70
View File
@@ -0,0 +1,70 @@
/**
* MetaMesh Plugin Types
*/
export interface PluginManifest {
id: string;
name: string;
version: string;
description?: string;
author?: string;
dependencies?: string[];
schema?: Record<string, SchemaField>;
config?: Record<string, ConfigField>;
priority?: number;
color?: string;
defaultQueue?: 'fast' | 'background';
timeout?: number;
}
export interface SchemaField {
label: string;
type?: 'string' | 'number' | 'boolean' | 'select' | 'text' | 'array' | 'json' | 'cid';
readonly?: boolean;
hint?: string;
}
export interface ConfigField {
type: 'string' | 'number' | 'boolean' | 'select';
label?: string;
required?: boolean;
default?: unknown;
secret?: boolean;
}
export interface HealthResponse {
status: 'healthy' | 'unhealthy';
ready: boolean;
version: string;
}
export interface ProcessRequest {
taskId: string;
cid: string;
filePath: string;
callbackUrl: string;
metaCoreUrl: string;
existingMeta?: Record<string, string>;
}
export interface ProcessResponse {
status: 'accepted' | 'rejected';
error?: string;
}
export interface CallbackPayload {
taskId: string;
status: 'completed' | 'failed' | 'skipped';
duration: number;
error?: string;
reason?: string;
}
export interface ConfigureRequest {
config: Record<string, unknown>;
}
export interface ConfigureResponse {
status: 'ok' | 'error';
error?: string;
}
tsconfig.json
+18
View File
@@ -0,0 +1,18 @@
{
"compilerOptions": {
"target": "ES2022",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"lib": ["ES2022"],
"outDir": "./dist",
"rootDir": "./src",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true,
"declaration": true,
"sourceMap": true
},
"include": ["src/**/*"],
"exclude": ["node_modules", "dist"]
}