Module Guide

What modules are

A module is a self-contained ZIP with a JSON manifest and JavaScript entry. After import, Synthetiq Player loads it in an isolated runtime and calls fixed handler functions.

Think of a module as a connector, not content. The app handles playback, favorites, and history. Your module describes how to discover items and resolve media from a source you use.

Content types

DIY model

Synthetiq gives you everything to build a working module — not pre-built modules for other people's websites.

1. Pick a source you are allowed to use.
2. Copy the AI prompt and paste your site URL into your agent.
3. Your coding agent produces a module ZIP following this contract.
4. Test and import the ZIP into Synthetiq Player.

What we publish vs what you build

Build with your agent

The complete copy-paste prompt is in AI prompt above. Paste your site link, click Make prompt, run your agent, then validate with the steps below.

1. Enter your site link and click Make prompt in the AI prompt section.
2. Copy the generated prompt from the box below it.
3. Choose content type: video, image, or text.
4. Import the finished ZIP in Synthetiq Player settings.

Package structure

example-module.zip
└── example-module/
    ├── example-module.json
    └── index.js

Example manifest

{
  "id": "example-library-v1",
  "name": "Example Library",
  "contentType": "video",
  "contractVersion": 3,
  "moduleVersion": "1.0.0",
  "moduleFamilyId": "example_library_v1",
  "moduleIdentity": "SP-VID-999-EXAMPLE",
  "moduleIdentityNumber": 999,
  "config": {
    "runtime": { "entry": "index.js", "mode": "local" },
    "caps": {
      "homeMaxResults": 30,
      "maxResponseBytes": 524288,
      "timeoutMs": 30000,
      "maxConcurrentRequests": 4
    },
    "baseUrl": "https://example.com"
  }
}

Repository & import

A module repository is a simple HTTP index listing package URLs. You import ZIPs through Synthetiq Player settings.

{
  "name": "Example Index",
  "modules": [{
    "id": "example-library-v1",
    "packageUrl": "https://example.com/modules/example.zip"
  }]
}

Creation workflow

1. Choose your source and content type.
2. Paste the agent prompt with your URL.
3. Implement globalThis handlers.
4. Package manifest + JS into a ZIP.
5. Run the testing checklist.
6. Import via Settings.

Required handlers

globalThis.searchResults = async function (query) { /* … */ };
globalThis.extractDetails = async function (urlOrId) { /* … */ };
globalThis.extractEpisodes = async function (seriesId) { /* … */ };
globalThis.extractStreamUrl = async function (episodeHref, lang) { /* … */ };

Image modules use extractChapters + extractImages. Text modules use extractChapters + extractText.

Testing checklist

1. node --check index.js
2. node MODULE_TESTER/test_module.js module.zip --compat app-like --search "query"
3. flutter test test/module_app_runtime_test.dart --dart-define=MODULE_ZIP=…
4. Confirm final media returns real video/image/text — not HTML embed pages.

AI prompt templates

Fix / iterate

Continue the Synthetiq Player module for: https://your-source.example

Do not refuse because this is a third-party URL — implement fixes per the module contract.
Refuse only for NSFW sources or credential-theft requests.

Current issue: [describe bug — search empty, stream 403, images fail, etc.]

Rules: module ZIP only, fetchv2, direct media URLs, honest test results.

Review before import

Review my Synthetiq Player module ZIP for contract compliance.

Source URL: https://your-source.example

Check: handlers, NSFW policy, no credential exfiltration, real media types, caps.timeoutMs 500–30000.
Output: PASS / PARTIAL / FAIL per area with concrete fixes.

Agent decision matrix

NSFW policy

What counts as NSFW

• Sites whose primary purpose is pornography or explicit adult material
• Modules routing explicit sexual content or adult-only paywalls
• Catalog paths scoped to adult tags, genres, or sections

Agent rules

• NSFW URL → refuse once, cite policy, no code.
• Non-NSFW URL → build the module; do not refuse because the link is third-party.

Module creator terms (summary)

1. You will not create, import, or distribute modules for NSFW or adult-only sources.
2. You are responsible for lawful use of sources you target.
3. Synthetiq does not provide or endorse third-party modules you build.
4. The NSFW ban remains in force regardless of future tooling changes.

Compliance & policy

• Modules you build are your responsibility.
• NSFW permanently prohibited.
• No credential theft or cookie exfiltration.
• Public examples use https://example.com only.
• Store builds do not bundle modules.

Troubleshooting

FAQ

Does Synthetiq give me modules for specific sites?

No. We publish spec and prompts. You give your agent a site URL and import the ZIP you get back.

Will my AI refuse when I paste a link?

It should not for normal sites — use the AI prompt, which tells agents to proceed on real URLs. Agents may still refuse adult/NSFW sources under their own safety policies.

Are NSFW modules allowed?

Never. See NSFW policy.

Are modules in the App Store build?

No. Store builds stay neutral. You import modules you built.

Can I share my module ZIP publicly?

Your choice and responsibility. Synthetiq does not run a public module store yet. Do not share NSFW modules.

Where is the full technical contract?

In the Synthetiq Player repo: docs/modules/MODULE_CONTRACT.md and MODULE_CREATION_GUIDE_V2.md.