Vejledning

Udvidelser til JtV

En udvidelse er en kilde til programmer. Den fortæller JtV, hvilke serier og afsnit den har, og giver en adresse at afspille, når et afsnit skal vises. JtV gør resten: kanaler, tv-plan, skærmtid, godnat. Hver serie bliver sin egen kanal, præcis som jeres egne videoer.

Udvidelser installeres af en forælder under Indstillinger > Udvidelser fra et GitHub-link. Denne vejledning er til jer, der vil lave en.

Hvad en udvidelse kan og ikke kan

Den kan:

Den kan ikke:

Det er bevidst. En udvidelse kører på en boks i et børneværelse og er skrevet af en fremmed. Den får det mindste, den skal bruge.

Rettigheder: en udvidelse må kun vise noget, som den, der installerer den, har ret til at se på den måde. Brug offentlige, frie samlinger eller tjenester, hvis vilkår tillader det. Udvidelser, der går uden om login, betaling eller kopibeskyttelse, hører ikke hjemme her.

Kom i gang på 10 minutter

Du skal bruge Bun 1.3 eller nyere og JtV's udviklersæt: én fil, som kører din udvidelse præcis som en JtV-boks gør. Du behøver hverken JtV's kode eller en boks.

curl -fsSLO https://JTV-SIDE/kit/jtv-plugin-kit.js
bun jtv-plugin-kit.js ny min-udvidelse "Mine tegnefilm"

Det giver:

min-udvidelse/
  jtv-plugin.json     manifestet
  index.ts            koden, med de fire funktioner klar til at fylde ud
  jtv-plugin.d.ts     kontrakten som typer
  README.md           hvad den gør, til forældre
  AGENTS.md           regler til Codex (samme tekst i CLAUDE.md til Claude)

bun jtv-plugin-kit.js guide viser hele denne vejledning i terminalen.

Manifestet: jtv-plugin.json

{
  "id": "arkivet",
  "name": "Internet Archive",
  "version": "1.0.0",
  "api": 1,
  "kind": "source",
  "entry": "index.ts",
  "description": "Gamle tegnefilm fra archive.org. Indsæt et link til en samling.",
  "author": "Dit navn",
  "homepage": "https://github.com/dig/jtv-arkivet",
  "domains": ["archive.org"]
}
FeltKrav
idsmå bogstaver, tal og bindestreg, 2–40 tegn. Bliver en del af stier og tjenestenavne, så skift den aldrig.
name, versionvises for forælderen. Højst 200 tegn.
api1
kind"source"
entryrelativ sti til en .ts- eller .js-fil inde i mappen
domainsde eneste værter, udvidelsen må tale med. Højst 20. archive.org dækker også ia800300.us.archive.org. Ingen IP-adresser, ingen porte.
description, author, homepagevalgfri, vises før installation

Nævn kun de domæner, du faktisk bruger. Forælderen ser listen, før de siger ja, og ser det igen, hvis en ny version vil have flere.

Koden: de fire funktioner

Filen i entry eksporterer et objekt som default:

import type { Plugin } from './jtv-plugin'

const plugin: Plugin = {
  async listSeries(ctx) { /* påkrævet */ },
  async resolve(episodeId, ctx) { /* påkrævet */ },
  async addSeries(input, ctx) { /* valgfri */ },
  async removeSeries(key, ctx) { /* valgfri */ },
}
export default plugin

listSeries(ctx) → PluginSeries[]

Alle serier med alle afsnit. Kaldes når boksen starter, én gang i døgnet og efter addSeries/removeSeries. Svaret erstatter det forrige helt.

return [
  {
    key: 'blender-film',                     // stabil; bliver kanalens nøgle
    title: 'Big Buck Bunny',
    seasons: [
      {
        number: 1,                        // valgfri
        episodes: [
          { id: 'bbb-01', title: 'Big Buck Bunny', durationSeconds: 597, episodeNumber: 1 },
        ],
      },
    ],
  },
]

Gå en tjeneste ned et øjeblik, så giv hellere det sidste gode svar (gemt i ctx.dataDir) end en tom liste. En tom liste fjerner kanalerne.

resolve(episodeId, ctx) → PluginStream

Kaldes lige før et afsnit vises. Giv en frisk adresse:

return { url: 'https://ia800300.us.archive.org/…/popeye.mp4' }
// eller video og lyd hver for sig:
return { url: 'https://…/video.mp4', audioUrl: 'https://…/audio.mp4' }

Adressen skal være http(s) og ligge på et af dine domæner. Mp4 med start= virker bedst: så kan JtV hoppe ind midt i et afsnit, som tv gør. Svar inden for 20 sekunder, ellers springer JtV afsnittet over.

addSeries(input, ctx) og removeSeries(key, ctx)

Har udvidelsen addSeries, får forælderen et felt "Tilføj fra link" under Udvidelser. input er det, de skrev (højst 500 tegn). Tjek det, gem det i ctx.dataDir, og kast en Error med en kort dansk tekst, hvis det ikke duer. Teksten vises for forælderen, så skriv den til dem: "Det er ikke et link til en samling", ikke "invalid identifier".

ctx

ctx.dataDirdin skrivbare mappe. Den eneste.
ctx.fetchfetch gennem JtV's proxy. Den globale fetch peger også derhen.
ctx.log(...)skriver til boksens log med dit id foran
ctx.manifestid, name, version, domains

Udvidelsen kører i sin egen Bun-proces. Node-moduler som node:fs og node:path virker. Der køres ingen npm install, så har du afhængigheder, så bundt dem til én fil (se Udgiv den).

Prøv den lokalt

bun jtv-plugin-kit.js test min-udvidelse https://archive.org/details/BigBuckBunny_124

Udviklersættet starter udvidelsen i sin egen proces bag den samme proxy som boksen, så en vært, der mangler i domains, bliver afvist her, ligesom den vil blive på boksen. Så kalder det addSeries (hvis du giver et link), listSeries to gange (id'erne skal være de samme), resolve på første afsnit i op til tre serier, tjekker svarene som JtV gør og prøver adresserne. Til sidst står, hvilke værter udvidelsen faktisk talte med. Data lægges i min-udvidelse/.data.

✓ manifest: Internet Archive 1.0.0, domæner: archive.org
✓ starter i egen proces; funktioner: listSeries, resolve, addSeries, removeSeries
✓ addSeries(https://archive.org/details/BigBuckBunny_124)
✓ listSeries: 1 serier, 1 afsnit
✓ id'er er stabile mellem to kald
✓ resolve(BigBuckBunny_124.0) -> archive.org (9:57)
✓ adressen svarer 206 video/mp4
✓ net: archive.org

Alt er ✓. Klar til at lægge på GitHub.

Vil du se og afspille det:

bun jtv-plugin-kit.js vis min-udvidelse <link>

åbner en side på http://127.0.0.1:1994 med serierne, afsnittene, hvad der ville køre på kanalen lige nu, og en afspiller.

Udviklersættet isolerer kun nettet (proxyen). Det er din egen kode på din egen maskine; den fulde lukning (egen bruger, ingen adgang til filer) sker først på boksen. Se Sikkerhed.

Udgiv den

  1. Bruger koden npm-pakker eller flere filer, så bundt den:
    bun jtv-plugin-kit.js pak min-udvidelse
    
    Det lægger index.js, manifestet (med "entry": "index.js") og README i min-udvidelse/build/. Udgiv indholdet af build/.
  2. Læg mappen i roden af et GitHub-repo (manifestet skal ligge i roden).
  3. Del linket: github.com/dig/jtv-arkivet. En bestemt gren eller tag: github.com/dig/jtv-arkivet/tree/v1.0.0.

JtV slår den commit op, linket peger på nu, og installerer netop den. Ingen automatiske opdateringer: vil forælderen have en ny version, indsætter de linket igen og ser forskellen (fx nye domæner), før de siger ja.

Private repos virker med en GitHub-nøgle med læseadgang. Nøglen bruges kun til at hente og gemmes ikke.

Grænser: højst 50 MB og 2000 filer. Symbolske links afvises.

Sikkerhed

Det her gælder på en JtV-boks (Raspberry Pi med JtV's installer). Det er lag, der gør skaden mindre, hvis en udvidelse opfører sig dårligt; ingen af dem er en garanti, så installér kun udvidelser fra nogen, I stoler på.

Uden systemd (på en udviklingsmaskine og i udviklersættet) kører udvidelser som almindelige processer, kun med proxyen som værn. JtV siger det på siden og nægter at gøre det på en boks i drift.

Finder du et hul, så skriv til DarkByte (sikkerhedsadresse kommer her) i stedet for at lægge det offentligt.

Udvidelser er lavet af andre end DarkByte. DarkByte gennemgår dem ikke og står ikke inde for dem eller for det, de viser.

Byg en udvidelse med Claude eller Codex

En AI-kodeassistent kan skrive det meste af en udvidelse, når den har kontrakten og en måde at tjekke sig selv. Udviklersættet giver den begge dele på din egen maskine: den bygger i en tom mappe og tester bag samme proxy som boksen. Den får ikke adgang til nogen JtV-boks.

Åbn Claude Code eller Codex i en tom mappe, kopiér prompten og ret de to første linjer:

Byg en JtV-udvidelse, der henter <hvad: fx "frie tegnefilm fra samlingen X">.
Kilde: <adresse på tjenesten og evt. dens API-dokumentation>.

JtV er en rolig børne-tv-kanal. En udvidelse er en kilde til serier og afsnit;
JtV laver kanaler, plan og skærmtid. Du har ikke JtV's kode og skal ikke bruge den.

1. Hent udviklersættet og læs vejledningen:
     curl -fsSLO https://JTV-SIDE/kit/jtv-plugin-kit.js
     bun jtv-plugin-kit.js guide
   (Kræver Bun 1.3+. Mangler det: curl -fsSL https://bun.sh/install | bash)
2. Lav udvidelsen: bun jtv-plugin-kit.js ny <id> "<navn>"
   og følg reglerne i <id>/AGENTS.md og kontrakten i <id>/jtv-plugin.d.ts.
3. Test efter hver ændring: bun jtv-plugin-kit.js test <id> <et rigtigt link>
   og ret, til alle linjer er ✓.

Regler:
- domains: kun de værter, koden faktisk henter fra. Find de rigtige værter for
  både API og videofiler (de ligger ofte på et andet underdomæne eller CDN).
- Stabile nøgler og afsnits-id'er, rigtig durationSeconds (spring afsnit uden
  længde over). Gem sidste gode svar i ctx.dataDir og brug det, hvis kilden fejler.
- addSeries: tjek input strengt, kast Error med kort dansk tekst til forældre.
- Kun ctx.fetch / fetch og node:fs i ctx.dataDir. Ingen child_process, intet
  uden for ctx.dataDir.
- Kun indhold, som tjenestens vilkår tillader at vise på den måde. Ingen omgåelse
  af login, betaling, geoblokering eller kopibeskyttelse. Kan det ikke lade sig
  gøre inden for det, så stop og sig det.

Vis mig til sidst testens output, listen over domæner og hvad hvert bruges til,
og sig hvad du ikke kunne afprøve.

Gode vaner, når en assistent skriver en udvidelse:

Fejlfinding

Det ser duDet betyder
"peger på X, som ikke står i domains"adressen ligger på en vært, der ikke er i manifestet. Tilføj den (og se om den skal).
"Proxy 403" i loggenudvidelsen prøvede at nå en vært uden for domains, eller ikke på port 443.
"svarede ikke i tide"et kald tog over 20 sekunder. Gem lister i ctx.dataDir i stedet for at hente alt hver gang.
"prøvede at nå X, som ikke står i domains" (test)tilføj værten til domains, eller fjern kaldet.
"kunne ikke starte"fejl ved indlæsning: forkert entry, en manglende fil eller en pakke, der ikke er bundtet.
Kanalen står på det forkerte steddurationSeconds passer ikke med videoen.
Afsnit springes overresolve fejlede; se boksens log: journalctl -u jtv -u 'jtv-plugin@*'.

Kontrakten er i jtv-plugin.d.ts, som ny lægger i mappen.