@thanh01.pmt/multimedia-kit

An autonomous Educational Multimedia Search Router, License Auditor, and Interactive Science Simulation Catalog Engine for LearnWell Platform.

🌟 Overview

multimedia-kit addresses the core challenge of educational content authoring: finding real, license-safe assets (photos, videos, vector diagrams) and interactive science simulations (PhET, LabNguyen) with zero friction.

It is split into two distinct engines:

1. Live Search Engine: Multi-provider REST search (Pexels, Pixabay, Unsplash, Openverse, Wikimedia Commons) with automatic provider routing, license safety filtering, LRU caching, and seamless fallback chaining.
2. Simulation Catalog Engine: Offline-seeded index of interactive STEM simulations with semantic concept matching, grade-level targeting, bilingual support (EN/VI), and responsive HTML iframe / Marp slide embed generation.

📦 Installation & Setup

pnpm --filter @thanh01.pmt/multimedia-kit build

Environment Variables (Optional)

# Free keys from providers (if omitted, zero-key public endpoints or fallbacks are used)
PEXELS_API_KEY=your_pexels_key
PIXABAY_API_KEY=your_pixabay_key
UNSPLASH_ACCESS_KEY=your_unsplash_access_key

🚀 Quick Usage

1. Search Educational Media

import { MediaSearchRouter, searchEducationalMedia } from '@thanh01.pmt/multimedia-kit';

// Standalone quick query
const photos = await searchEducationalMedia({
  query: 'Arduino ESP32 breadboard',
  mediaType: 'photo',
  licenseFilter: 'commercial_safe',
  maxResults: 5,
});

// Advanced Router with provider override
const router = new MediaSearchRouter();
const vectors = await router.search({
  query: 'electric circuit schematic',
  mediaType: 'vector', // Automatically prioritized to Pixabay
  maxResults: 6,
});

2. Interactive Simulations Catalog

import { ConceptMatcher, EmbedGenerator, findScienceSimulations } from '@thanh01.pmt/multimedia-kit';

// Semantic search
const sims = findScienceSimulations({
  query: 'khúc xạ ánh sáng',
  subject: 'physics',
  gradeLevel: 9,
  language: 'vi',
});

console.log(sims[0].title); // "Bending Light"
console.log(sims[0].titleVi); // "Khúc xạ ánh sáng"

// Generate responsive HTML embed
const iframeHtml = EmbedGenerator.generateIframe(sims[0]);

// Generate Marp presentation slide
const marpSlide = EmbedGenerator.generateMarpSlide(sims[0]);

3. License Auditing & Attribution Generation

import { AttributionBuilder, LicenseAuditor } from '@thanh01.pmt/multimedia-kit';

const isSafe = LicenseAuditor.isCommercialSafe(asset.license);
const creditsMd = AttributionBuilder.generateMarkdown([asset1, asset2]);

🧪 Testing

pnpm --filter @thanh01.pmt/multimedia-kit test