HatchLing-TuneBox / README.md
taellinglin's picture
Lamp: the SVG over the lightbox, and layered UV print files
509f053 verified
|
Raw History Blame Contribute Delete
31.4 kB

A newer version of the Gradio SDK is available: 6.32.0

Upgrade
metadata
title: HatchLing-TuneBox
emoji: 🎵
colorFrom: indigo
colorTo: red
sdk: gradio
sdk_version: 5.23.1
app_file: app.py
pinned: false

HatchLing-TuneBox

Turns photos into A4 outline-and-crosshatch sheets in the Ling style: one SVG on white and one on black per image. It also turns Ling programs into functional maps in the same style, SVG files into Ling programs (see "Ling programs" below), and any of the three into a packed globe (see "Globe").

What it can be used for

  • Pen plotters, laser engravers and vinyl cutters. Every sheet is clean vector line work (one SVG on white, one on black) at a set line weight, so it plots, engraves or cuts without tracing.
  • Posters, prints and cards. Turn a photo, a logo or a coat of arms into a poster in the Ling style; the patriotic presets (America, Korea, Ling Country, Reitenland) give flag-coloured sheets with a country's mottoes in the rings.
  • Signed, verifiable artwork. Each sheet is drawn from an ML-DSA-87 signature of its source, so the same picture and key phrase always give the same sheet, and the signature can be checked. Useful for limited editions, certificates, coins and stamps.
  • Seeing how a program is built. A Ling program becomes a functional map (and a map gives its program back), so a codebase can be read as a picture, or an SVG can be turned into a program that redraws it.
  • Music visuals. Give a MIDI file, a recording, or both, and the globe or music box plays the tune through a circuit of dials: animated SVG sheets, a spinnable globe, or a page with the sound. Suited to album art, lyric or concert visuals, and music teaching.
  • Teaching. A hands-on way to show FFT onset detection, k-means colour clustering, hatching geometry and post-quantum signatures.
  • Branding for a community or project. The theme and preset system is easy to extend with your own colours and slogans (themes.py, ling_tiles.py).

Patriotic themes

The Preset dropdown on the Pictures tab dresses the whole app, and the sheets it makes, in a country's colours, background and slogans:

Preset Colours Background Slogans
patriotic America red, white and blue official portrait of Bill Clinton (public domain, White House) E Pluribus Unum, We the People, Putting People First
patriotic Korea taegeuk red and blue, black, white the Taegukgi, drawn by make_assets.py 대한민국 만세, 홍익인간, 무궁화 삼천리 화려강산, 파이팅
patriotic Ling Country navy, gold and red of the flag the Ling flag, from ling-gov.org 天圆,地方 (Heaven is a Circle, Ground is a Square), Balance, Harmony, Reciprocity, plus 天下為公, 为人民服务, 和, ชาติ ศาสนา พระมหากษัตริย์
patriotic Reitenland orange, red and white the flag: three horizontal stripes, drawn by make_assets.py Reitenland, Orange Red and White (no motto added)

themes.py holds the colours and mottoes; python make_assets.py portrait.jpg flag.png rebuilds assets/.

GPU

With PyTorch and a CUDA device, the colour clustering and the label smoothing run on the GPU (gpu.py); everything else is the same OpenCV code. It is used automatically, and HATCHLING_GPU=0 turns it off. A sheet made on the GPU can differ from the CPU one in about 0.1% of label pixels. On Hugging Face, set the Space hardware to ZeroGPU: the handlers that reach these steps are wrapped in @spaces.GPU.

MIDI and a recording together

In the Globe and Music box tabs you can give both a MIDI file and a recording (WAV, MP3, OGG or FLAC) of the same tune. The MIDI keeps every pitch and length. The recording's FFT is used to (1) line the MIDI up with the sound, by cross-correlating their onsets (shifts of up to 3 s, found to about 20 ms), (2) set each note's strength, half from the MIDI velocity and half from how strongly the recording shows that pitch, (3) add drum hits the recording has and the MIDI lacks, and (4) play the real recording in the music box instead of the built-in synth. On the command line: --midi tune.mid --wav tune.wav. A recording alone still works, as before (all notes then come from the FFT).

Enhanced choreography

In the Music box tab, Enhance choreography turns the tune into a show across the whole circuit instead of one pulse running down the wires (ling_dance.py). Every note sets off a move timed by where each dial sits on the face, and the move changes every two bars:

  • ripple: rings spread from the centre; kick drums beat outward, snares and hats beat inward (circular symmetry)
  • waterfall: a column chosen by the note's pitch lights from the top and cascades down
  • sweep: a radar arm swings round the face from the note's pitch-class angle, one way then the other
  • march: the beat is a march; warm hues and even rows step on the left foot, cool hues and odd rows on the right
  • spiral: delay grows with angle and radius, so arms wind in or out (a twist)
  • kaleidoscope: six-fold mirror symmetry spreading from the middle

The colours are turned about as well: in some sections a note lights only its own hue (and the complement), in others everything except that hue. The beat is taken from the drums, or from how the notes are spaced.

Even mosaic across the face

Seen from the front, a piece's width shrinks toward the edge of the globe as the surface turns away. So the pieces are sized to look the same from the front: finer in the middle, larger on the sphere toward the edge. This keeps the picture readable across the whole face instead of dissolving into slivers at the rim. view_even sets how much (1 is the default, 0 gives equal pieces on the sphere; --view-even 0 on the command line).

Sizes, orientation and layout

Every sheet (pictures, Ling program maps, music boxes) can be drawn on paper (A5, A4, A3, A2, A1, US Letter, Tabloid) or on a screen, phone, tablet or projector size (iPhone, Android, iPad, laptops, HD, Full HD, QHD, 4K, 8K, ultrawide, XGA, WXGA, DCI 4K, square and story posts). A screen sheet keeps the device's shape and its SVG is given the real pixel size. Orientation can be auto, portrait or landscape. The key (legend, dial, digest, title plate) can go at the bottom, top, left or right, and on the music box the piano roll can too; at the sides the key is scaled to fit the sheet and the roll runs up the side. Command line: --paper fhd --orientation landscape --key-side left.

Dice and board (3D)

The Dice and board (3D) tab runs the globe's system on other shapes, and turns the pieces into real objects.

  • Shapes. A picture is projected straight on to a tetrahedron (d4), cube (d6), octahedron (d8), dodecahedron (d12) or icosahedron (d20), to the globe, or onto a flat board like a Reactable table. It is packed with dials and tiles, face by face (ling_dice.py), and wired into the same circuit that plays a MIDI file or a recording (or the tune the signature writes). The page is the globe page: drag to spin, click a dial to send a pulse.
  • 3D objects (.glb). Every dial and tile is its own object in a binary glTF (ling_gltf.py) that opens in Blender (File > Import > glTF 2.0), Unity, Godot, three.js and model-viewer. Dials can be cylinders, cones, domes, spheres, hexagonal prisms, rings, cubes, pyramids, or a different shape for each key (cone for asm, sphere for lit, cube for bind, cylinder for ctl, dome for call, hexagonal prism for fn, ring for mod). Tiles are slabs; signal dials stand taller. Wires are thin tubes in the key's colour. Each object carries its key, tone, signal number and name as custom properties. They stand on the die, a ball, or a round or square board, sized in metres (0.9 m across for the board, 0.3 m for the rest, or your own).

MIDI patches and channels

A MIDI file's patch (instrument) changes are read, so every note knows which General MIDI patch was selected on its channel when it sounded (gm.py; channel 10 is the drum kit).

  • A colour for each channel. Drums are red; the other channels take one of the seven key colours each, in the order they first sound. On the globe, dice and board page a pulse lights its dials in the colour of the channel that sent it, and a legend under the title lists each channel with its patch. In the music box the track round the frame and the piano roll draw each channel's notes in its colour.
  • A timbre for each patch family. The synth (in the page and in the music box's sound) plays the 16 General MIDI families differently: a plucked triangle for pianos, a bright held square for organs, filtered saws for guitars, basses, strings, ensembles and brass, soft reeds and pipes, slow pads, and so on. Patch changes midway through a piece change the sound from that note on.
  • Choreography. With several channels, the colour-turning sections of the enhanced choreography follow the note's channel colour instead of its pitch class.

Lamp (3D print) and the music box

The Lamp (3D print) tab makes a physical version of the picture: a light sculpture you can print. Every piece becomes a mirrored cell (the wireframe extruded: line the walls with mirror film), and every cell is fed by its own filament (clear 1.75 mm filament or optical fibre) running through a printed conduit from an LED in a housing at the side. About a hundred cells need only one row of small RGB LEDs on a thin PCB.

  • The conduit block (ling_lamp.py): the cell walls on a slab cut through with smooth conduits. Each lit cell has a straight lane from the side of the block, then a quarter turn up (a 12 mm radius by default) to a port in the middle of its cell floor. Lanes are assigned so they never cross. Round and square cells, any convex panel: a rectangle or circle, or a die's face (triangle, square, pentagon), one panel for each face.
  • LED bays: a housing on each side with a bore for every filament, a slot for the LED strip PCB (LED centres at the lane pitch, 3 mm for 2020 packages), a trough for wires and a lid.
  • led_map.csv gives, for every LED, its place on the strip, its cell, its key colour and the length to cut the filament. animation.rgb is the enhanced choreography as RGB frames, one colour per LED per frame, for the LEDs to play, with a starting player.ino (ESP32, untested on hardware).
  • Also make the music box adds (ling_enclosure.py, ling_pcb.py):
    • an enclosure: a tray with a compartment for the electronics, a ring and grille for a speaker, openings for USB, power, microSD, a knob and two buttons; and a bezel with a window the shape of the panel;
    • a solid colour plug for every cell, one STL for each key colour. The walls between cells run right to the front so each cell is a lightproof box, and its plug (a face over the walls and a tongue that corks into the cell) lights as one flat colour, not a blur. Print each file in a translucent filament of that colour;
    • KiCad files: a 110 x 75 mm controller carrier for a Raspberry Pi Pico (plays the MIDI or WAV from a microSD card through a MAX98357A I2S amp module, reads MIDI in through a 6N138, drives two 74AHCT125 level-shifted LED outputs, with an encoder, two buttons and a 5 V input), and the outlines of the LED strips with a marker and number at every LED. The carrier's parts and nets are placed but it is not routed, and the files have not been opened in KiCad: check the footprints against your parts. The strips leave the LED footprint to you, because packages differ between makers. They parse and round-trip in the kiutils KiCad parser.
    • The firmware is not included.

The SVG over the lightbox, and UV print files

Every lamp comes with lightbox_preview.html (also shown in the tab): the lightbox from the front, with the cells in their colours, the conduits and LEDs, and the SVG the picture's pieces would draw laid over it (the dial rings and the tile hatch of the music box), with switches for each layer, the line colour, its weight and its opacity.

The same artwork comes as print files at the panel's true size (ling_overlay.py), all with the same origin and registration marks: uv_print.svg (layers), and uv_white.svg (spot white), uv_colour.svg (each cell in its key colour), uv_lines.svg (0.2 mm black linework) and uv_cut.svg (a magenta hairline round every plug, to cut them from coloured acrylic). For a backlit box, print the colour directly on clear or opal acrylic with no white under it, then the black lines over it; for an opaque picture print white first. UV_PRINT_NOTES.txt has the details. Colours are sRGB, so proof them: the RIP converts to CMYK.

Run

pip install -r requirements.txt
python hatchling.py                # the app (Gradio), opens on http://127.0.0.1:7860
python hatchling.py musicbox a.png --audio tune.mp3 --layout flat --key false --roll true    # any tool by name: hatch, tiles, map, globe, musicbox
python ling_hatch.py a.jpg b.png --out sheets --hues 5 --coding spectrum    # command line
python ling_map.py project.zip --out maps                                   # a Ling program as a map
python ling_map.py drawing.svg --out ling                                   # an SVG as a Ling program
python ling_globe.py a.png --midi tune.mid --ling --out globes              # a globe to spin, driven by a MIDI file
python ling_musicbox.py a.png --midi tune.mid --out boxes                   # an A3 animated SVG that plays the tune

Each image gives <name>_white.svg, <name>_black.svg, a preview PNG of each, and all.zip with every SVG.

What it does

  1. Crops the image to the picture area of the sheet (never stretches it), or fits the whole image if you choose that.
  2. Posterizes it into up to seven colour regions, one Ling hue each, and up to four hatch densities per hue.
  3. Signs the image file with ML-DSA-87 and uses the signature bytes to pick each hue's hatch family, angle and period.
  4. Traces every region to an outline and fills it with clipped hatch lines. Nothing is filled.
  5. Draws the frame, legend, dial, digest and title plate with the Ling component bundle (ling_bundle.js).

The signature is a visual encoding. It does not protect or authenticate the print.

Options

Option Meaning
layout instruments: picture plus legend, dial, digest and title plate. picture: picture only, portrait or landscape.
crop, anchor fill crops to the picture area and anchor says which part to keep. fit keeps the whole image.
hues, steps Colour regions (3 to 7) and hatch densities per hue (2 to 4).
coding perceptual: many colour clusters, each keeps its own hue (nearest hue angle; neutrals take the nearest hatched appearance). cryptographic: seven regions ordered light to dark take the hues in an order shuffled by the signature. appearance: seven regions, one hue each, nearest overall. spectrum, spectrum-reversed: red to violet by lightness.
analysis_px, smooth, simplify, min_region How fine, how smooth and how small the regions may be.
contrast, gamma, tone_weight Local contrast, mid-tone darkness, and whether regions follow tone or colour.
vivid Colour strength. 0: density follows light and dark only. 1: saturated colours get dense hatch. -1 (default): auto, 0 for photos rising to 0.5 for flat, saturated artwork.
keep_transparent Transparent parts of a PNG stay empty: no hatch and no outline. Turn off to treat them as white.
dpi, line_mm, spacing_mm, quality Coordinates sit on the dpi grid. Spacing below 0.22 mm is under the Ling print floor.
key_phrase Empty: fresh random key per image, discarded. Set: key derived from the phrase, same image gives same hatch.
black_ground Turn off to print the black version on black stock.

Tiles and text rings

python ling_tiles.py photo.jpg --out sheets (or Style: "Tiles and text rings" in the app) packs each colour region with square tiles and circles instead of hatching it. Pieces never cross a region edge and are placed largest first, so flat areas get large pieces and detailed areas small ones. Circles carry rings of text spelling the hue's key, set in Chesilin with one glyph per ring cell (--ring-face lingring for Ling Ring); circles too small for text show the hue's node shape. Tiles are hatched at the region's density and the larger ones carry the hue's spectrum letter (R O Y G B I V) in Daemon (--tile-face lingring for Ling Ring). --png-scale 2 also writes PNGs at twice screen size (1588 x 2246 for A4). Options: ring_face, tile_face, circle_bias, mix, tile_min_mm, circle_min_mm, circle_max_mm, tile_max_mm, gap_mm, ring_text.

--animate true writes a screen version whose SVG carries CSS animation: rings turn at different speeds and directions, ring glyphs spark or light one by one, hub shapes and tile letters turn, larger tile frames light in a wave across the sheet, and each hue's second hatch direction fades out and back. Only transforms and fades are animated, with no filters or glows, and lit colours stay inside their own hue. It honours the reduced-motion setting. For screens use lighter settings, for example --quality draft --line-mm 0.25 --spacing-mm 0.42 --tile-min-mm 0.7 --gap-mm 0.15.

--preset patriotic gives a red, white and blue poster: --coding tonal --palette call,asm,call,fn cuts the picture into flat tone bands (pale blue, red, blue, navy from light to dark), every hub is a star (--hub-shape star), lettered tiles carry a star (--tile-text "★"), and the rings read E PLURIBUS UNUM, WE THE PEOPLE, LIBERTY and USA in Ling Ring capitals (--ring-text takes several phrases separated by |; each ring uses the longest that fits). It sets a key phrase and seed, so the same picture always gives the same sheet.

density_sizing caps piece size by tone, so dense tones get smaller pieces where the regions are large enough to matter.

Ling programs

python ling_map.py project.zip --out maps (or the "Ling programs" tab in the app) takes a .zip, a folder or single .ling files and draws one sheet, on white and on black.

  • Panel: one file. Its name is on the tab.
  • Dial: one function. The hub holds its node shape; the program's entry (bind start = do { ... } and the other entry names Ling accepts) holds 灵 and sits at the centre of its panel, with the functions it calls placed outward from it. The first ring is the function's statements in order, clockwise from the top. The next ring is what each statement contains, and the next what those contain (--rings, 1 to 4). The outer ring spells the name, in Chesilin, or in the name's own script when Chesilin lacks the letters (Thai, Chinese, Korean and so on, from fonts on the machine).
  • Colour: what the code does. Red (asm): inline assembly, hardware, windows, input. Orange (lit): literals, drawing, sound and other media. Yellow (bind): bindings, assignments, collections, types. Green (ctl): if, match, loops, return, timing. Blue (call): calls to the project's own functions, I/O, network. Indigo (fn): computation. Violet (mod): modules, imports and the entry. Builtins are recognised in every language Ling's lexicons cover (ling_keywords.json, taken from the Ling repository).
  • Hatch: each colour's hatch family (torus, Möbius, tetrahedral), angle and period come from an ML-DSA-87 signature of the program. Density says how much code a cell holds: up to 8 tokens, 24, 72, more. The foot of the sheet shows every colour at every density.
  • Tiles: globals with their values, and types with their members, in Daemon.
  • Lines: blue from a caller to the function it calls (the diamond is at the callee, heavier when called more than once); violet between a file and a file it imports with use.
  • Foot: legend, the share of each colour in the program, the SHA3-256 of the program in tiles, and the title plate.

Options: --paper a4|a3|a2|auto (auto makes the sheet as large as print-size lettering needs; the SVG metadata and the app say whether the smallest lettering meets the 3.5 mm print floor), --orientation, --rings, --edges false, --title, --key-phrase (same program, same sheet), --grounds, --png-scale 2. Code the reader cannot follow is skipped in the map and counted; the stored program is always complete.

SVG to Ling

Every map carries its program: the files, their SHA3-256, the public key and the signature are in <metadata id="ling-source">, and each drawn cell has data-ling="file:start-end" (character offsets), data-kind and data-name. python ling_map.py map.svg --out restored checks the signature and writes the files back, byte for byte (and a zip when there are several). As with the picture sheets, the signature shows the file was not changed since it was made; the key is made for the occasion, so it does not say who made it.

This is also how a picture becomes a Ling program: make its sheet (hatch or tiles), then run ling_map.py on the sheet's SVG, or tick "Also write each sheet as a Ling program" in the app. An A4 tile sheet is about 50,000 strokes and a 6 MB program.

Any other SVG becomes a Ling program that redraws it (--mode draw forces this for a map too): paths, curves and arcs, rectangles, circles, ellipses, lines, polygons, transforms and inherited colours are flattened into svg_polyline and svg_line calls, grouped into one function per colour and line weight and called from bind start. Ling's svg_rect and svg_circle are filled, so they are used for filled rectangles and circles; other filled shapes are outlined and crosshatched in their colour. Text, images and gradients are not drawn. ling run name.ling writes name_redrawn.svg.

Globe

python ling_globe.py picture.png --out globes (or the "Globe" tab) writes picture_globe.html: a sphere you can spin, packed with dials and tiles. Open it in a browser. It takes a picture, an SVG, or a Ling program (.zip, folder or .ling files).

  • The shell. Every piece is flat and stands on the plane that touches the sphere at the piece's own centre, so all are the same distance from the middle. They are packed on the shell itself: largest first, each inside one region, then each grown until it meets its nearest neighbour or its region's edge.
  • Dials are signal nodes. A pulse that reaches a dial lights its ring letters as far round as its level, turns its rings, and runs on along its wires. What else it does follows its key: asm strobe (flashes), lit lamp (brightens, fades slowly), bind latch (flips and stays; its two meter tiles swap places), ctl timer (ticks a twelfth of a turn at a time while the note lasts), call relay (shifts its hue, passes the pulse on late), fn actuator (turns one way when the tune rises and the other when it falls), mod bus (deepens in colour, passes on the most).
  • Tiles. A lettered tile wired to a dial by a pin is that dial's meter: its hatch fills from the bottom to the dial's level, it shrinks on each pulse, and it splits into four when the dial is driven hard.
  • Wires arc over the shell from a dial's rim to another dial or to a meter's pin. A pulse is seen running along the wire and the far end answers when it arrives.
  • Pulses come from a MIDI file (--midi tune.mid, or "Load MIDI" / drag and drop on the page), from a recording (--audio tune.mp3: see "Music box" for how its impulses are found), from the tune the signature writes when there is none, from clicking a dial, and from sensor plates: a strobe's first meter fires its dial when you turn it to face you. Pitch chooses where a note enters: low notes near the root, high notes far from it; drums enter at the strobes. "Sound" plays the tune with a plain synth so you can hear it in step.
  • Sources. A picture is posterized and laid on the front of the sphere (mirrored on the back); the root is the dial nearest its middle. With --crop fit the whole picture is kept and wrapped round the sphere from the front, like a cloth over a ball, so a tall picture runs over the top and under the bottom (--wrap-deg, 115 by default: how far round its edge reaches). Transparent parts, and whatever the picture does not reach, are filled with the --field key (mod; none leaves them bare). An SVG that carries a Ling program is read as that program; any other SVG is used as a picture. For a Ling program every function is a territory, sized by its code: its dial in the middle spells its name, ringed by tiles for its statements; the entry faces you; wires between dials are the calls.

On the page: drag to spin, scroll or pinch to zoom, arrow keys and + / - also work, click a dial to pulse it and read what it is. Buttons: see through, turn slowly, wires, white ground, load MIDI, reset view, pause, sound. It needs WebGL 2.

--ling also writes picture_globe.ling, the globe as a Ling program. ling run picture_globe.ling draws the side that faces you as picture_globe_frame.svg, with every dial and tile as the circuit has it at seconds into the tune (--at 8, or change at and turn at the top of the file). The program holds the pieces' line work, the wiring and the tune, and works the circuit out itself with the same rules and numbers as the page.

Options: --samples (how finely the shell is measured; 1,000,000 takes about a minute), --circle-max-deg, --circle-min-deg, --tile-max-deg, --tile-min-deg, --gap-deg, --circle-bias, --mix, --node-min-deg (dials at least this large are signal dials), --meters, --links, --rings (Ling programs), --midi, --wrap-deg, --field, --title, --key-phrase, and the picture options of ling_hatch.py.

Music box

python ling_musicbox.py arms.png --midi anthem.mid --out boxes (or the "Music box" tab) writes one animated SVG sheet, A3 by default (--paper a4|a3|a2), on black (--grounds white black for both).

  • Layout. --layout globe shows the face of the globe (--turn, --tilt choose the side), inside the Ling dial bezel. --layout flat packs the same dials and tiles flat across the sheet, like the tile sheets, and wires them the same way. A picture's transparent parts become a quiet field of smaller pieces that carry no signals (--field none leaves them bare).
  • Key. --key false leaves out the legend, colour shares, digest and title plate, so the picture takes the whole sheet.
  • Track and playhead. Just inside the frame runs a track with every note on it: round the frame by when it sounds (clockwise from the top left), across the track by pitch, drums along the inside edge, each in the colour of the dial it enters at. A playhead, a small dial with a line across the track, travels the frame once per loop.
  • Piano roll. --roll true adds a window where the notes slide past a fixed line (--roll-seconds, 8 by default, is how much it shows at once): pitch upward, one rule per octave, drums along the bottom.
  • The performance. As the playhead passes a note, the note's pulse runs through the circuit by the same rules as the globe page, and each dial it reaches answers: its ring letters and rim light and fade (a strobe sharply, a lamp slowly, a relay in a shifted hue), a timer's rings tick a twelfth of a turn at a time, an actuator's turn with the rise and fall of the tune, a latch's two meter tiles change places, a meter splits in four when its dial is driven hard, and wires flash as a pulse leaves. All of it is worked out beforehand and written into the SVG as CSS animation of opacity and transform, so the file plays on its own in a browser: no script, and no sound.
  • The tune. --midi tune.mid, or a recording with --audio tune.mp3 (wav, mp3, ogg, flac; anything but WAV needs ffmpeg or pip install soundfile). A recording is cut into short frames, each frame's spectrum (FFT) is gathered into semitone bands, and where a band's energy jumps above what it has lately been, that onset becomes an impulse: a note at that band's pitch, as strong as the jump, lasting until the band falls back to half. A jump across most bands at once is a drum hit. The impulses then drive everything exactly as MIDI notes do. With no tune, the signature writes one.
  • Loop. --seconds 60 --start 0 choose the part of the tune (0 seconds: all of it). A pulse that would arrive after the loop ends arrives at the start of the next, so the loop has no seam. --max-stops caps how many moments one dial's animation holds; a long tune is thinned to fit, so a shorter loop follows the notes more closely.
  • Sound, zoom and pan. <name>_musicbox.html holds the same sheet and the tune as sound (a recording as it is, a MIDI file through a plain synth). On that page the sheet zooms with the wheel, a pinch, or + and -, moves when dragged or with the arrow keys, and "Whole sheet" (or 0) brings it back.
  • Keeping time. The page plays the sound through Web Audio as one seamless loop and reads the sound card's own clock: every animation that follows the tune is given the same start, set from the moment the sound is actually heard, and is put back if it ever drifts more than 6 ms. "Picture later by" moves the picture a few milliseconds either way, for speakers that add a delay of their own (wireless ones mostly). --hop (0.1 s) is how long a pulse takes along one wire: smaller keeps each dial's answer closer to its note, 0.2 matches the globe page.

It takes every option of ling_globe.py (--crop fit, --circle-max-deg, --samples, ...), and with the globe layout --ling also writes the globe as a Ling program.

Files

  • ling_tiles.py: the tile-and-ring packer. Needs LingRing-Variable.ttf beside it and fonttools.

  • ling_hatch.py: the pipeline, a library and a command-line tool.

  • ling_globe.py: pictures, SVG files and Ling programs as interactive globes. Needs globe_template.html beside it.

  • ling_musicbox.py: the globe and a MIDI file as one animated SVG sheet.

  • ling_map.py: Ling programs to maps and SVG to Ling. Needs ling_keywords.json beside it.

  • ling_keywords.json: Ling's keywords and builtins in every lexicon language, with a colour for each builtin.

  • hatchling.py: one way in to every tool (python hatchling.py starts the app).

  • app.py: the Gradio app.

  • ling_bundle.js: the Ling design system component bundle. Replace it to follow the design system.

  • hub_glyph.json: outline of 灵 for the dial hub (from Noto Sans CJK SC, SIL OFL 1.1).

The frames and legend need a JavaScript engine: mini-racer (in requirements) or, failing that, Node.js on the PATH.

Support

HatchLing-TuneBox is free. If it is useful to you and you would like to chip in toward its development, you can donate through PayPal. Thank you.