Jabbertoon for developers

The question Jabbertoon answers for developers is: how do I turn a script into an animated, talking cartoon in code? This page is the part of that answer that works today. From code, or from an AI assistant, you can:

It takes about five minutes, and none of it needs a key, an account or a payment. The step that finishes the answer is in section 4.

The simplest way to use Jabbertoon from code, or from an AI assistant, is to write a link. The move travels inside the link after the # sign, so you need no server and no API call:

  1. Write a program. This one is a whole move: one script that bobs the body 8 pixels and swings the head 6 degrees.

    {
      "v": 1,
      "kind": "behaviour",
      "name": "nod and bob",
      "scripts": [
        {
          "body": [
            {
              "op": "bob",
              "amp": 8,
              "every": 1
            },
            {
              "op": "swingPart",
              "part": "head",
              "deg": 6,
              "every": 1.5
            }
          ]
        }
      ]
    }
  2. Turn it into canonical JSON: keys sorted at every level, no spaces. This is the exact text the code is made from.

    {"kind":"behaviour","name":"nod and bob","scripts":[{"body":[{"amp":8,"every":1,"op":"bob"},{"deg":6,"every":1.5,"op":"swingPart","part":"head"}]}],"v":1}
  3. Encode that text as UTF-8, then base64url without padding (the + and / of base64 become - and _, and the = at the end is dropped). That is the share code.

    eyJraW5kIjoiYmVoYXZpb3VyIiwibmFtZSI6Im5vZCBhbmQgYm9iIiwic2NyaXB0cyI6W3siYm9keSI6W3siYW1wIjo4LCJldmVyeSI6MSwib3AiOiJib2IifSx7ImRlZyI6NiwiZXZlcnkiOjEuNSwib3AiOiJzd2luZ1BhcnQiLCJwYXJ0IjoiaGVhZCJ9XX1dLCJ2IjoxfQ
  4. Put the code after #move= in a link to the editor. Opening the link shows the move as blocks in the Forge's move maker and plays it on a person; nothing is sent to a server, because the browser never sends the part after the #.

    https://jabbertoon.com/cartoon/#move=eyJraW5kIjoiYmVoYXZpb3VyIiwibmFtZSI6Im5vZCBhbmQgYm9iIiwic2NyaXB0cyI6W3siYm9keSI6W3siYW1wIjo4LCJldmVyeSI6MSwib3AiOiJib2IifSx7ImRlZyI6NiwiZXZlcnkiOjEuNSwib3AiOiJzd2luZ1BhcnQiLCJwYXJ0IjoiaGVhZCJ9XX1dLCJ2IjoxfQ

In the move maker, Use it keeps the move in the person's own moves, and every character in their cartoon can do it. A whole cartoon travels the same way: the code of a cartoon program ({"v": 1, "kind": "cartoon", ...}, with its cast, places and scenes) after https://jabbertoon.com/cartoon/#c= opens it in the editor, where it plays, and the person who opens it gets a copy of their own to change and save as a video (what they were making is kept: one tap switches back). share_link makes that link for you, and checks the cartoon first. A character travels the same way, as the code of {"type": "character", "name": ..., "content": ...}: after https://jabbertoon.com/cartoon/#c= it joins the cartoon open in the editor. A ready-made character needs no code at all: https://jabbertoon.com/cartoon/#ch=dog puts Grump, the dog of the cast in 3D, in a new cartoon. The link formats are listed in the link reference, and the program format in the block language reference.

2. Call the free tools

The same tools that AI assistants use are plain HTTP endpoints at https://jabbertoon.com/api/<tool>, described by an OpenAPI document: make_cartoon turns a script, a line each, into a cartoon and the link that plays it, in one call; get_guide gives one topic of the guide (call it first); list_moves and list_characters list what Jabbertoon ships; get_move gives a move's program and its readable text; validate checks a move, a character or a cartoon; share_link turns a cartoon, a move or a character into a link; build makes a thing, a move, a game or a place to walk from its steps and gives the link that opens it; and read_blueprint measures a floor plan's picture so build can make the building. They are free and keyless, and all of them but report_problem and read_blueprint only read. Each example below checks a move and gets the link that opens it, against the live site, https://jabbertoon.com, and needs no key, no account and nothing to install beyond curl, Python or Node. (The variable at the top of each file can send it to another address; we use it to test our own server before a release, and you can leave it unset.)

curl

#!/bin/sh
# Jabbertoon quickstart (curl): check a move, then get the jabbertoon.com link that opens it.
# No key, no account. For a local server: JABBERTOON_BASE=http://127.0.0.1:8790 sh quickstart.sh
BASE="${JABBERTOON_BASE:-https://jabbertoon.com}"

# A move: bob up and down and swing both arms (the language: https://jabbertoon.com/docs/language/)
PROGRAM='{"v": 1, "kind": "behaviour", "name": "Happy bob",
  "scripts": [{"body": [{"op": "bob", "amp": 12}, {"op": "swingPart", "part": "arms", "deg": 30}]}]}'

# 1. validate: "ok": true, or each error and warning as {code, where, says, fix}
curl -sS -X POST "$BASE/api/validate" -H 'Content-Type: application/json' -d "{\"program\": $PROGRAM}"
echo

# 2. share_link: "link" opens the move in the Forge's move maker, where it plays. The move travels in the
#    link after the #, so nothing is uploaded or stored.
curl -sS -X POST "$BASE/api/share_link" -H 'Content-Type: application/json' -d "{\"program\": $PROGRAM}"
echo

Save it as quickstart.sh, then run it: sh quickstart.sh.

Python

"""Jabbertoon quickstart (Python 3, standard library only): check a move, then get the link that opens it.
No key, no account. For a local server: JABBERTOON_BASE=http://127.0.0.1:8790 python quickstart.py"""
import json, os, sys, urllib.error, urllib.request  # noqa: E401

BASE = os.environ.get('JABBERTOON_BASE', 'https://jabbertoon.com')
PROGRAM = {'v': 1, 'kind': 'behaviour', 'name': 'Happy bob',   # a move: bob and swing both arms (/docs/language/)
           'scripts': [{'body': [{'op': 'bob', 'amp': 12}, {'op': 'swingPart', 'part': 'arms', 'deg': 30}]}]}


def call(tool, args):
    req = urllib.request.Request(f'{BASE}/api/{tool}', data=json.dumps(args).encode('utf-8'),
                                 headers={'Content-Type': 'application/json'})
    try:
        text = urllib.request.urlopen(req, timeout=20).read()
    except urllib.error.HTTPError as e:   # a refusal is JSON too (busy, timeout, too_large ...)
        text = e.read()
    if not text.lstrip().startswith(b'{'):   # not the Jabbertoon API at all (a web page, a proxy's error page)
        sys.exit(f'{tool}: the answer from {BASE} is not JSON: is that the Jabbertoon API?')
    answer = json.loads(text)
    if 'error' in answer:
        sys.exit(f"{tool}: {answer['error']['code']}: {answer['error']['says']} (fix: {answer['error']['fix']})")
    return answer


check = call('validate', {'program': PROGRAM})            # 1. ok, or {code, where, says, fix} for each problem
for p in check['errors'] + check['warnings']:
    print(f"{p['code']} at {p['where']}: {p['says']} (fix: {p['fix']})")
if check['ok']:
    print('Open it:', call('share_link', {'program': PROGRAM})['link'])   # 2. the link carries the move after the #

Save it as quickstart.py, then run it: python3 quickstart.py.

JavaScript (Node 18 or later)

// Jabbertoon quickstart (JavaScript: Node 18+ or a browser): check a move, then get the link that opens it.
// No key, no account. For a local server: JABBERTOON_BASE=http://127.0.0.1:8790 node quickstart.mjs
const BASE = (globalThis.process && process.env.JABBERTOON_BASE) || 'https://jabbertoon.com';

// A move: bob up and down and swing both arms (the language: https://jabbertoon.com/docs/language/)
const program = {
  v: 1, kind: 'behaviour', name: 'Happy bob',
  scripts: [{ body: [{ op: 'bob', amp: 12 }, { op: 'swingPart', part: 'arms', deg: 30 }] }],
};

async function call(tool, args) {
  const r = await fetch(`${BASE}/api/${tool}`, {
    method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(args),
  });
  let answer;   // every answer is JSON, a refusal too (busy, timeout, too_large ...)
  try { answer = JSON.parse(await r.text()); } catch (e) { throw new Error(`${tool}: the answer from ${BASE} is not JSON (HTTP ${r.status}): is that the Jabbertoon API?`); }
  if (answer.error) throw new Error(`${tool}: ${answer.error.code}: ${answer.error.says} (fix: ${answer.error.fix})`);
  return answer;
}

const check = await call('validate', { program });          // 1. ok, or {code, where, says, fix} for each problem
for (const p of [...check.errors, ...check.warnings]) console.log(`${p.code} at ${p.where}: ${p.says} (fix: ${p.fix})`);
if (check.ok) {
  const made = await call('share_link', { program });       // 2. the link travels with the move after the #
  console.log('Open it:', made.link);
}

Save it as quickstart.mjs, then run it: node quickstart.mjs.

The tools, their arguments and an example of each are listed on the page for AI assistants.

3. Check your files against the schemas

Programs, packs and cartoons have JSON Schemas at their public URLs, so your editor or your tests can check a file before Jabbertoon sees it. The pack format explains what each file holds.

4. What comes next

One thing finishes the answer to the question above, and it is not yet published: turning a script into a video in code, with a command-line renderer and library that run on your own machine, free and with no key. It is not yet published, so there is nothing to install or run for it today; this page will say when there is. Until then, validate checks a whole cartoon, share_link turns it into a link that plays it in the editor, where it is saved as a video.

The source

Jabbertoon's code belongs to 1211 Holding LLC, all rights reserved. The part of it that runs in your browser is served as it was written, not minified, so you can read it and check what it does; reading it is not a licence to reuse it (for a licence, write to hello@jabbertoon.com). The engine starts at /engine/index.js, which imports the rest of it; the code that draws the characters and runs the block editor is under /ui/. Every file:

The code of the tools for AI assistants runs on our server and is not served; the OpenAPI document and the page for AI assistants describe exactly what each tool takes and gives back.

Data rights