diff --git a/src/plugin.ts b/src/plugin.ts index 57378a0..7408169 100644 --- a/src/plugin.ts +++ b/src/plugin.ts @@ -21,11 +21,17 @@ * Matroska stream tags already carry. A `fra` member would be dropped by a * `languages:fre` filter. * - * ⚠ Audio only. Consumers read `languages/*` as the AUDIO-language set - * (meta-watch `cards::audio_languages`); subtitle-track languages belong to - * `subtitleLanguages/*` (subtitle-extractor). Title keys are not a source - * either: `titles/` names the language of a TITLE (tmdb files - * `originalTitle` under `original_language`), not of the file's audio. + * ⚠ Audio only as a SOURCE — but it writes two keys, not one. This plugin reads + * audio tracks, so the codes it finds are audio languages and land in + * `audioLanguages/`; every one of them is ALSO written to + * `languages/`, the union that queries filter on (METADATA_KEYS §9, + * rule #7 — "a union field is written, never computed"). Nothing reconciles the + * two after the fact, so a record with the split set and the union unset is + * invisible to every language filter on every peer. Subtitle-track languages + * belong to `subtitleLanguages/*` (subtitle-extractor), which owes the union + * member for the same reason. Title keys are not a source either: + * `titles/` names the language of a TITLE (tmdb files `originalTitle` + * under `original_language`), not of the file's audio. * * ⚠ No `titles/*` write. The old `titles/{firstAudioLang || 'eng'}` = * `originalTitle` guess overwrote better identity (tmdb, jellyfin-nfo, @@ -41,8 +47,8 @@ import { MetaCoreClient } from './meta-core-client.js'; export const manifest: PluginManifest = { id: 'language', name: 'Language Aggregator', - version: '1.1.0', - description: 'Adds audio-track languages to the languages/ key-set', + version: '1.2.0', + description: 'Adds audio-track languages to the audioLanguages/ and languages/ key-sets', author: 'MetaMesh', dependencies: ['ffmpeg'], priority: 40, @@ -50,6 +56,7 @@ export const manifest: PluginManifest = { defaultQueue: 'fast', timeout: 30000, schema: { + audioLanguages: { label: 'Audio languages', type: 'array', readonly: true }, languages: { label: 'Languages', type: 'array', readonly: true }, }, config: {}, @@ -170,23 +177,41 @@ export function audioLanguagesFromMeta(existingMeta: Record | u } /** - * Whether the record already carries `languages/`, in either shape: the - * flat key, or the nested `languages: { : ... }` object meta-sort's - * reconstructed document holds. + * Whether the record already carries `/`, in either shape: the flat + * key, or the nested `: { : ... }` object meta-sort's reconstructed + * document holds. */ -function hasMember(existingMeta: Record | undefined, code: string): boolean { +function hasMember( + existingMeta: Record | undefined, + field: string, + code: string, +): boolean { if (!existingMeta) return false; - if (existingMeta[`languages/${code}`] !== undefined) return true; - const nested = existingMeta['languages']; + if (existingMeta[`${field}/${code}`] !== undefined) return true; + const nested = existingMeta[field]; return !!nested && typeof nested === 'object' && !Array.isArray(nested) && (nested as Record)[code] !== undefined; } -/** The `languages/` members to add — never one the record already has. */ +/** + * The members to add — never one the record already has. + * + * Each audio code is written TWICE: once to `audioLanguages/` (what this + * plugin actually observed — a spoken track) and once to `languages/` + * (the union every query filters on). METADATA_KEYS §9 rule #7 makes the second + * write mandatory, not a convenience: the union is stored, never computed, and + * a query cannot ask for `audioLanguages OR subtitleLanguages` — the gateway + * wire ANDs across keys, so an OR of the splits would return strictly less. + */ export function languageWrites(existingMeta: Record | undefined): Record { const writes: Record = {}; for (const code of audioLanguagesFromMeta(existingMeta)) { - if (!hasMember(existingMeta, code)) writes[`languages/${code}`] = 'true'; + if (!hasMember(existingMeta, 'audioLanguages', code)) { + writes[`audioLanguages/${code}`] = 'true'; + } + if (!hasMember(existingMeta, 'languages', code)) { + writes[`languages/${code}`] = 'true'; + } } return writes; } diff --git a/test/language.test.ts b/test/language.test.ts index ee0e1f3..d53d907 100644 --- a/test/language.test.ts +++ b/test/language.test.ts @@ -164,18 +164,47 @@ describe('audioLanguagesFromMeta', () => { }); describe('languageWrites', () => { - it('skips members already present in the flat or nested form', () => { - expect(languageWrites(nestedDoc({ 'languages/jpn': 'true' }))).toEqual({ 'languages/eng': 'true' }); - expect(languageWrites(nestedDoc({ languages: { eng: 'true', jpn: true } }))).toEqual({}); + it('writes each audio code to BOTH the split and the union (METADATA_KEYS §9 rule #7)', () => { + expect(languageWrites(nestedDoc())).toEqual({ + 'audioLanguages/jpn': 'true', + 'languages/jpn': 'true', + 'audioLanguages/eng': 'true', + 'languages/eng': 'true', + }); + }); + + it('skips members already present in the flat or nested form, per field', () => { + // The union is already there; the split is not — the record still owes + // the split, and vice versa. The two are tracked independently. + expect(languageWrites(nestedDoc({ 'languages/jpn': 'true' }))).toEqual({ + 'audioLanguages/jpn': 'true', + 'audioLanguages/eng': 'true', + 'languages/eng': 'true', + }); + expect(languageWrites(nestedDoc({ languages: { eng: 'true', jpn: true } }))).toEqual({ + 'audioLanguages/jpn': 'true', + 'audioLanguages/eng': 'true', + }); + expect( + languageWrites(nestedDoc({ audioLanguages: { eng: 'true', jpn: 'true' }, languages: { eng: 'true', jpn: 'true' } })), + ).toEqual({}); }); }); describe('process', () => { - it('writes the audio languages/* key-set from the nested payload in one merge', async () => { + it('writes the audio split AND the union from the nested payload in one merge', async () => { const { callback, writer } = await run(nestedDoc()); expect(callback?.status).toBe('completed'); expect(writer.calls).toEqual([ - { hashId: 'cid-1', metadata: { 'languages/jpn': 'true', 'languages/eng': 'true' } }, + { + hashId: 'cid-1', + metadata: { + 'audioLanguages/jpn': 'true', + 'languages/jpn': 'true', + 'audioLanguages/eng': 'true', + 'languages/eng': 'true', + }, + }, ]); }); @@ -183,14 +212,27 @@ describe('process', () => { const flat = Object.fromEntries(REAL_STREAMS.map((s, i) => [`stream/${i}`, s])); const { callback, writer } = await run(flat); expect(callback?.status).toBe('completed'); - expect(writer.calls[0].metadata).toEqual({ 'languages/jpn': 'true', 'languages/eng': 'true' }); + expect(writer.calls[0].metadata).toEqual({ + 'audioLanguages/jpn': 'true', + 'languages/jpn': 'true', + 'audioLanguages/eng': 'true', + 'languages/eng': 'true', + }); }); - it('never writes titles/* or any non-languages key, even with originalTitle and title keys', async () => { + it('every split member has a matching union member — the record is never left half-written', async () => { + const { writer } = await run(nestedDoc()); + const keys = writer.calls.flatMap((c) => Object.keys(c.metadata)); + for (const k of keys.filter((k) => k.startsWith('audioLanguages/'))) { + expect(keys).toContain(`languages/${k.slice('audioLanguages/'.length)}`); + } + }); + + it('never writes titles/* or any non-language key, even with originalTitle and title keys', async () => { const { writer } = await run(nestedDoc({ 'titles/eng/Better Title': 'true', titles: { jpn: { '番組': 'true' } } })); const keys = writer.calls.flatMap((c) => Object.keys(c.metadata)); expect(keys.length).toBeGreaterThan(0); - expect(keys.every((k) => k.startsWith('languages/'))).toBe(true); + expect(keys.every((k) => k.startsWith('languages/') || k.startsWith('audioLanguages/'))).toBe(true); expect(keys.some((k) => k.startsWith('titles'))).toBe(false); }); @@ -209,10 +251,23 @@ describe('process', () => { }); it('is idempotent: a re-run over a record that already has the members writes nothing', async () => { - const { writer } = await run(nestedDoc({ 'languages/jpn': 'true', 'languages/eng': 'true' })); + const { writer } = await run(nestedDoc({ + 'audioLanguages/jpn': 'true', 'audioLanguages/eng': 'true', + 'languages/jpn': 'true', 'languages/eng': 'true', + })); expect(writer.calls).toEqual([]); }); + it('backfills the union on a record written before the split existed', async () => { + // Pre-1.2.0 records carry only `languages/*`. A re-run must add the + // split without disturbing the union that is already correct. + const { writer } = await run(nestedDoc({ 'languages/jpn': 'true', 'languages/eng': 'true' })); + expect(writer.calls[0].metadata).toEqual({ + 'audioLanguages/jpn': 'true', + 'audioLanguages/eng': 'true', + }); + }); + it('fails the task when the write is rejected', async () => { const { callback } = await run(nestedDoc(), new RecordingWriter(false)); expect(callback?.status).toBe('failed');