TiLiE is a local browser editor and visualization tool for musical timelines represented by the Python timetoalign library. It edits a workspace, a canvas of blocks. A block places one manifest on the canvas: a TimeToShare manifest of the one shape every manifest has, holding root timelines (each with exact coordinates, child offsets, conversion maps, regions and flow control), optionally grouped into timeline groups, beside the measure maps its conversion maps read, and the statements that say what the manifest, its timelines and its regions stand for: works, recordings, editions, the people involved. A manifest knows nothing about where it is shown.
Status: alpha. The editor described below is in the source tree. The tilie-server release on PyPI predates it and serves only the application shell: it installs, serves the bundled editor on 127.0.0.1 with a fresh token for each run, and reports its health.
What works in the source tree:
- Manifests and workspaces (
core). Manifests of TimeToShare schema 0.2.0, the current version, with exact numbers:- validated load of any manifest in YAML or JSON, completed with every default it leaves out, and save in the complete or the minimal form, with or without its styling, in canonical YAML, pretty JSON or RFC 8785 JSON;
- unknown keys kept and written back, and timelines of unknown length;
- the statements of TimeToShare's description specification, property–value pairs with their provenance, on the manifest, its timelines and its regions, each element's set as a whole; a held manifest keeps of its JSON-LD
@contextonly the prefixes it declares itself, and every file it is written to carries the full context; - element addresses, and the workspace view with its blocks, ids and order keys;
- the four commands
add,set,removeandstyleover addresses, under the library's invariants; - a store whose command journal gives undo and redo;
- the workspace file
<name>.tle.json(format version 7), named by default after the workspace.
- Drawing (
layout,writers). Every manifest is drawn as one block opened by its title, a manifest without timelines as that block and title alone:- groups as frames, and each timeline as a root in a card; a member of several groups gets a card in each of their frames;
- a member that is a child timeline drawn under the lines of its ancestors;
- a timeline of unknown length scaled to its content and ending in three chevrons;
- named MatchStamps, each alignment anchor a line between its two match timestamps, the MatchStamp's name at the middle one;
- element descriptors, SVG and TikZ as the TimeToShare drawing specification defines them.
- The canvas (
arranger), built on Svelte Flow. Each completed gesture is one undoable command.- Blocks are dragged with snapping, reordered, selected and deleted, and so are timelines, groups and the other elements of a manifest, except segments, whose deletion is not supported yet.
- A press on a box selects that box, a timeline's cards, a group's frame or the block; the card or frame under the pointer is highlighted.
- Every block, frame and card is resized in the same three modes, Scale, Box and Stretch. A member's card is resized in the frame it is worked in, its size stated through that group.
- Editors on the canvas. A double-click opens a block, a group or a timeline in its bundle, group or timeline editor.
- Done, or a double-click outside the edited element, keeps the changes as one journal entry; Cancel discards them.
- Undo takes back a closed editor's changes by runs: the consecutive changes made in that editor and not in one nested in it. In the open editor its own changes are undone one at a time. Redo re-applies what undo took back, step for step.
- In a timeline editor, the edited timeline's bands (markers, conversion maps, children, regions and flow control, stacked above and below its line) are selected and moved by drag, or by Ctrl or Cmd and an up or down arrow. Each move is one command that sets the timeline's band order in its manifest.
- In the bundle editor, groups' frames and ungrouped timelines' cards are dragged freely. Dragging one that is in the selection moves everything selected by the same travel and keeps the selection.
- The editor (
editor). One component that the page served bytilieuses, and that any other page can mount withpnpm build:embed'stilie.js(embedding). Among its options,storage.userKeyandstorage.profilesKeyname thelocalStoragekeys of the user and of the type profiles (the page served bytilieusestilie.userandtilie.profiles; without a key nothing is stored), andlookup: falseturns every lookup request off.- A header with a File menu (New workspace, Open…, Save, Save as…, Import manifest…, Export manifest…, Your name…, Type profiles…), an Examples menu that adds one of four example manifests from TimeToShare as a new block or opens the example workspace "Timestamps" in place of the open one (asking first to save or discard unsaved changes), and an About button, the canvas, and an inspector drawer opened by a tab at the right edge.
- Manifests are imported from TimeToShare manifest files in YAML or JSON, each as a new block at the centre of the view, moved right past the blocks it would overlap (an open editor is closed first, as Done closes it). Export writes each bundle back as its file came: in the minimal or the complete form, with or without its styling, and in canonical YAML, pretty JSON or RFC 8785 JSON, the file named after the manifest's
id, else itsname, elsebundle. A new bundle is written minimal, with its styling, in YAML; the Manifest tab sets Minimal and Include styling for each bundle, and the workspace keeps these settings. - The inspector's first tab, named by the level in view (Arranger, Bundle, Group or Timeline), names the workspace or the edited element. Its Properties tab renames the workspace or the inspected element, edits the geometry of the selected block, frame or card, puts the selected timelines into groups or takes them out (a timeline may be in several groups), lists a selected group's members to change them, and creates a new group of the selected timelines. Its Metadata tab shows and edits statements (below). Its Manifest tab shows the selected block's manifest as Export writes it, as JSON, YAML or TOML, edits it, and lists unknown keys and the manifest's own warnings. Its Journal tab lists the journal, newest first.
- Statements. The Metadata tab shows what the selected bundle, timeline or region stands for (with nothing selected, the edited element in an editor, else the bundle when the workspace holds one block), as property–value pairs that TimeToShare's description specification defines, each with its provenance: how it was made (who stated it, when and how) and who believes it (true, unlikely or false). One tile holds one verb about one thing, collapsed to its sentence; the first one says what the element is ("Clair de lune, mm. 1–6 (MEI) is a printed or scanned edition."). One click on a tile's expand button shows its pairs, one row per vocabulary that states it (
rel:prf,schema:byArtist,wdt:P175, …), each with a Details button, and "+ Add vocabulary". Details shows the pair's paradata and beliefs and holds the actions: your own belief, True, Unlikely or False, and Remove; believing a pair false records your belief and leaves the pair stated. Below the tiles, the candidates (pairs held only in provenance, such as matches proposed for review) are listed with the same details, believing one true states it, and those you believe false are set apart. "+ Add statement" opens the composer, three fields each narrowing the next: the verb, the vocabulary, and the value, searched in Wikidata, the GND, YouTube or MusicBrainz, entered as an identifier, or a timeline or region of the manifest chosen from a list or picked on the canvas; a URL pasted into any field fills vocabulary and value, and "Other property…" states a property no vocabulary of the catalogue offers. "+ Add vocabulary" offers what other systems say the thing is the same as. "Propose matches for unreconciled names" looks up every name stated without an identifier and writes the best match as a candidate. Every action is one undoable command. What you add is stated by you and believed true by you: your name, "Gerhardt" until you give one under File, Your name…, is also the journal's author, and your ORCID iD, where you give one, names you in the provenance (else atag:IRI made from your name); the browser keeps both. Type profiles (File, Type profiles…) are your own types of thing, with the verbs usually stated of each and the systems to look its values up in, any Reconciliation Service API endpoint among them; they are settings of the browser, exchanged as YAML files, never part of a workspace or a manifest. - Lookup and privacy. Text typed into a value field goes to the chosen system's service: Wikidata, the GND (through lobid) and YouTube's oEmbed are asked from the browser, MusicBrainz only through
tilie-server(one request a second, a User-Agent naming the server and no person, answers cached for the run). Viewing the tab also resolves the IRIs of the things its tiles name, for their thumbnails, and "+ Add vocabulary" resolves a tile's thing for its cross-references, so the manifest's thing IRIs reach Wikidata, the GND, YouTube or the server. An editor mounted withlookup: falsesends none of these requests. - Timestamps. A timestamp is a timeline's cross-section at a position: the timeline's coordinate, that of every segment and displayed descendant its cross-section line crosses, and the values of their conversion maps. With Show coordinates on (the canvas toolbar, or C), hovering a timeline or one of its maps shows that timestamp in a flag, the position picked on the hovered row, and a click pins it in the Timestamp tab: there its exact values are copied bare, with their unit written out (
219/16 quarters) or pretty (13 11/16 ♩,1′15.5″), shown as JSON, YAML or TOML, and edited, every coordinate and every map value that can be solved for a position. Giving a pinned timestamp a name stores it in the manifest as a named timestamp, whose Display toggles choose what every export draws of it: its wedge, its name, ID and coordinate as stacked labels, and its dashed cross-section line. Every new root timeline, and every root of an imported manifest without agraphicalobject, is given the named timestampsoriginandlength(when its length is known), each drawing its wedge and coordinate; a timestamp at a timeline's end follows the end when the length changes. With Show coordinates off, a click on a named timestamp shows it in the tab, where it is renamed, moved by editing its values, or deleted. Two settings at the bottom of the tab cap how finely a position is picked: Denominator (2520 by default) for fraction axes and Decimals (3) for float axes, which also sets how values are rounded in the flag; the pointer takes the simplest value inside its pixel on the hovered row's axis, and zooming in reaches finer ones. Confirmations such as "Copied" appear in the message bar over the canvas and vanish after three seconds; warnings stay until dismissed. - MatchClaims and MatchStamps. A package's MatchClaims lie in its MatchClaim table, a Parquet file beside the manifest; the editor reads one table per block through
tilie-server, so matches need a server. A table is picked beside its manifest in Import manifest… or beside its workspace in Open…, going to the block whose manifest names its file, or with Load MatchClaims… in the Matchstamp tab; a block whose manifest names a table that is not loaded says so in the message bar. Tables are held while the workspace is open and never written into it. With Show matches on (the canvas toolbar, or M; it and Show coordinates take turns), the table's potential MatchStamps, the connected sets of alignment anchors its MatchClaims state, are drawn over the block as dashed grey lines; hovering one shows its coordinates in a flag, and a click pins it in the Matchstamp tab. There its coordinates are shown exact, or as JSON, YAML or TOML; giving it a name stores it in the manifest as a named MatchStamp, whole, as the table states it, even where the MatchClaim filter hides some of its timelines; its anchors' Line and Name toggles choose what every export draws. The tab lists the MatchClaims behind it, each with every actor's belief and, read from the server for these MatchClaims only, how it was made; True, Unlikely and False record your own belief, which the server writes into a new table, kept only once Save MatchClaims… saves it (New workspace and Open… ask before they drop a changed table). A named MatchStamp that the table no longer matches is shown out of date, with what differs, and Update rewrites it from the table; an anchor the table no longer states is drawn red. With Show matches off, a click on a MatchStamp's connector selects it for renaming, Update and Remove. The MatchClaim filter at the bottom of the tab chooses the timelines whose MatchClaims are shown and whether those you do not believe false or only those you believe true count; the workspace keeps it for each block. - Unsaved changes are marked with
•in the header. A workspace's text is autosaved in the browser's IndexedDB and offered for restoring when the editor opens again.
Not available yet: loading sources through timetoalign on the server, which so far exposes /api/health, /api/measure-maps, the expansion of a manifest's measure maps, /api/match-claims, a package's MatchClaim table checked against its manifest and answered as columns, /api/match-claims/provenance and /api/match-claims/belief, a MatchClaim's provenance read on demand and a belief recorded in a new table, and /api/reconcile/musicbrainz, MusicBrainz as a Reconciliation Service API 0.2 endpoint.
pip install tilie-server
tilietilie starts the local server on 127.0.0.1, port 8000, and opens the browser (the release on PyPI, which predates this, chooses a free port each time). The browser keeps what the editor remembers, such as your name and your type profiles, for each port apart, so the port stays the same from run to run; while port 8000 is taken, tilie uses a free port and prints a notice saying so. Use tilie --check to verify an installed distribution. tilie --port 43129 selects a port, and tilie --no-browser starts without opening a browser.
The server binds only to 127.0.0.1, creates a random bearer token for each run, rejects foreign Host and Origin headers, serves the bundled application, protects every /api/ route, and sends Referrer-Policy: no-referrer with every response. tilie prints and opens http://127.0.0.1:<port>/#token=<token>: the token travels in the URL fragment, which the browser never sends to the server. The editor reads it, removes it from the address bar, and sends it with its health request. The token is held in memory only, so reloading the page loses it and the header then shows the "offline" mark; restart tilie for a fresh URL.
Of the six application packages, core implements the workspace, block, and manifest model described in the architecture guide. It reads and writes manifests of schema 0.2.0 only, the one version TimeToShare supports, and migrates nothing. layout exports draw(manifest, placement, layers, metrics), which returns one derived drawing. writers exports toDescriptors(drawing), writeSvg(placed), and writeTikz(placed, options); a placed drawing has drawing, x, y, and scale, and a page may contain more than one. arranger exports the canvas and the functions that turn its gestures into commands (the canvas); editor is the application around it (the editor); client connects to the server and asks its health, the expanded rows of a manifest's measure maps, the columns of a package's MatchClaim table, the provenance of some of its MatchClaims and the new table holding a belief. There is no generated API client, server-side loading or export endpoint yet.
TiLiE keeps a small browser editing core and treats the local Python server as an equal peer for loading, computation, and exports. TimeToShare manifests remain exact and schema-validated, while the screen drawing is derived from them. The package structure prevents UI dependencies from leaking into the core. Read the architecture guide for the complete design and the distinction between current behavior and intended behavior.
Every application package that uses the TimeToShare schema package, @timetoalign/timetoshare, takes it through a link: to the js/ directory of a checkout beside this repository until schema 0.2.0 is published on npm, and ^0.2.0 from npm once it is. Clone TimeToShare there and build its js/ package first (see CONTRIBUTING.md), then install and validate the application workspace:
git clone https://github.com/TimeToAlign/TimeLineEditor.git
cd TimeLineEditor/app
pnpm install
pnpm lint
pnpm typecheck
pnpm test
pnpm buildTo render the writer review sheet, install rsvg-convert and run this from
the repository root:
pnpm -C app/packages/writers reviewThe command writes SVG and PNG renders plus index.html under
app/packages/writers/review/. It confines fontconfig to the DejaVu Sans and
Noto Music files bundled by TimeToShare and refuses to render when another font
is visible.
Set up, test, and build the server separately. Until a timetoalign release carries the measure-map expansion, the server installs timetoalign from a checkout beside this repository, so clone timetoalign there first; until a TimeToShare release carries schema 0.2.0, the timetoshare package that timetoalign checks statements with comes from the TimeToShare checkout cloned above (see CONTRIBUTING.md):
cd ../server
uv sync
uv run pytest
uv buildThe writer compile test needs lualatex with TikZ, standalone, and fontspec; it uses the DejaVu Sans and Noto Music files bundled by TimeToShare. Without lualatex the TikZ compilation is skipped, and with TILIE_REQUIRE_LUALATEX=1 set its absence is a failure, as in CI. The same test parses every review SVG as XML.
The server wheel bundles the built app. From server/, uv run tilie --check --static-dir ../app/packages/editor/dist checks a development build. From the repository root, python3 scripts/check_versions.py --tag vX.Y.Z checks that a release tag matches both declared versions.
Release preparation, version checks, the tag-triggered workflow, and PyPI trusted publishing are documented in CONTRIBUTING.md.
TiLiE is released under the MIT License. It depends on the timetoalign library, which is distributed separately.