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
- Kom i gang på 10 minutter
- Manifestet: jtv-plugin.json
- Koden: de fire funktioner
- Prøv den lokalt
- Udgiv den
- Sikkerhed
- Byg en udvidelse med Claude eller Codex
- Fejlfinding
Hvad en udvidelse kan og ikke kan
Den kan:
- hente lister over serier og afsnit fra de domæner, den har nævnt i manifestet
- give en video-adresse (mp4, mkv eller HLS
.m3u8), evt. med et separat lydspor - tage imod et link, som forælderen indsætter (fx en samling eller en serie)
- gemme sine egne filer i én mappe
Den kan ikke:
- se jeres videoer, indstillinger, forældrekode eller andre udvidelser
- tale med andre adresser på nettet end dem i manifestet (heller ikke jeres eget net)
- styre afspilleren, skærmtiden eller hvad barnet ser hvornår
- opdatere sig selv. Den bliver på den version, forælderen installerede.
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"]
}
| Felt | Krav |
|---|---|
id | små bogstaver, tal og bindestreg, 2–40 tegn. Bliver en del af stier og tjenestenavne, så skift den aldrig. |
name, version | vises for forælderen. Højst 200 tegn. |
api | 1 |
kind | "source" |
entry | relativ sti til en .ts- eller .js-fil inde i mappen |
domains | de 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, homepage | valgfri, 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 },
],
},
],
},
]
id: bogstaver, tal,.,_,-; højst 128 tegn. Skal være den samme næste gang, ellers mister kanalen sin plads i planen.durationSeconds: hele sekunder, større end 0. Tv-planen og skærmtiden bygger på den, så den skal være rigtig. Kender du den ikke, så spring afsnittet over.thumbnailUrl: valgfri, skal ligge på et af dine domæner.- Højst 100 serier og 3000 afsnit pr. serie.
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.dataDir | din skrivbare mappe. Den eneste. |
ctx.fetch | fetch gennem JtV's proxy. Den globale fetch peger også derhen. |
ctx.log(...) | skriver til boksens log med dit id foran |
ctx.manifest | id, 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
- Bruger koden npm-pakker eller flere filer, så bundt den:
Det læggerbun jtv-plugin-kit.js pak min-udvidelseindex.js, manifestet (med"entry": "index.js") og README imin-udvidelse/build/. Udgiv indholdet afbuild/. - Læg mappen i roden af et GitHub-repo (manifestet skal ligge i roden).
- 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å.
- Egen bruger, egen proces. Hver udvidelse kører som en midlertidig
systembruger (systemd
DynamicUser) medjtv-plugin@<id>.service. Den kan ikke læse JtV's data, videoer eller/boot, og kan ikke skrive andre steder end sin egen mappe. - Kun de nævnte domæner. Udvidelsen har kun adgang til
localhost. Alt andet net går gennem JtV's proxy, som kun åbner https (port 443) til domænerne i manifestet, og kun med en nøgle, der er lavet til netop den udvidelse. Adresser i det lokale net afvises. - Alt tjekkes. Svar fra udvidelsen valideres (typer, længder, domæner) før de bruges. Et kald, der hænger, afbrydes efter 20 sekunder.
- Begrænset. 192 MB hukommelse, 60 % af én kerne, 64 tråde.
- Fastlåst version. Installation kræver forældrekoden igen og viser kilde, commit og domæner først.
- Kan slås fra. En udvidelse kan slås fra eller fjernes under Udvidelser.
JTV_PLUGINS=offslår dem alle fra ved start.
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:
- Læs selv
domainsogREADME.mdigennem, før du deler den. - Kør
testselv. "Det burde virke" er ikke en test. - Se den med
visog afspil et par afsnit. - Bed den forklare, hvor længderne kommer fra. Forkerte længder giver en forskudt tv-plan.
Fejlfinding
| Det ser du | Det 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 loggen | udvidelsen 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 sted | durationSeconds passer ikke med videoen. |
| Afsnit springes over | resolve fejlede; se boksens log: journalctl -u jtv -u 'jtv-plugin@*'. |
Kontrakten er i jtv-plugin.d.ts, som ny lægger i mappen.