Caller's Compendium

Imports & migration

This guide is about getting dances into Caller's Compendium and moving your whole library between devices. It covers bringing in single dances from The Caller's Box and ContraDB, importing signed published collections and Caller's Compendium files, moving a whole library across from Caller's Companion, and backing up and restoring everything you own.

Finding your way around these words. On-screen buttons and screens are written in bold — like Settings, Import…, and Choose file…. The first time a dance term appears it links to the Glossary, so you can get a plain-language definition without losing your place.

Your data stays yours

Caller's Compendium is local-first. Your collection lives on your own device, the app works fully offline, there is no account to create, and nothing you do is sent anywhere for tracking. Importing and exporting are the doors your dances walk through — the ways you bring material in from the wider community and carry your own library from one machine to the next. Nothing leaves your device unless you ask for it (an online search or a single dance import reaches out once, when you tell it to), and nothing changes your collection until you say so.

Nothing gets lost when a dance comes in

Every import follows one promise: bringing a dance in never loses the dance.

When the app reads a dance from another source, it recognises the figures it can and turns them into structured moves you can search and rework. Anything it does not recognise — an unusual phrasing, a complicated sequence, a note the choreographer tucked into a line — is kept word-for-word as a plain-text figure instead of being dropped. A dance can arrive entirely as plain text and still land safely in your collection, still be searchable, and still be yours to tidy up later. You are never left wondering what the app quietly threw away, because it throws nothing away.

The app also shows you where that happened. A figure kept word-for-word carries a small warning glyph beside it — on a dance card, in the editor, and in Perform. Hover it on a desktop, or select it on a touchscreen, and it explains itself: Couldn't parse this call — kept verbatim as a custom figure. It is a shape, not just a colour, and it is announced to screen readers, so you can find the lines worth tidying up whichever way you read.

There is nothing wrong with leaving them as they are. A verbatim figure calls perfectly well; the badge just tells you the app cannot search or count beats for that line the way it can for a recognised move.

Bring in single dances from an online archive

Caller's Compendium can reach two community archives — The Caller's Box and ContraDB — two ways: a live online search, and importing a single dance by its link or ID number. Both need an internet connection, and both bring in one dance at a time so you can look before you keep.

Search an archive online and import a dance

  1. Open Collection.
  2. Open the Advanced panel above the dance list and turn on the Online search switch. (Your local filters do not apply while online search is on — you are searching the archive, not your own library.)
  3. Choose which archive to search — The Caller's Box or ContraDB — from the online source selector.
  4. Choose Title, Author, or Figure in the Search in menu, then type in the search box. Results appear as you type. With The Caller's Box you can also narrow by the figures a dance contains, using the same By phrase panel as a local search. The Collection & search guide explains how each option matches.
  5. Select a result to open a preview of that dance.
  6. If it is the one you want, choose Import to add it to your collection.

Caller's Box results only include dances whose figures it will share. Not every dance in The Caller's Box has its choreographer's permission for the figures to be shown — for some, the Box can search the figures but not display them. Those dances would come in as a title and a formation with no figures at all, so a Caller's Box search leaves them out. About three in ten of the dances matching a typical search are affected, so if a dance you know is in the Box does not appear, this is the likely reason. You can still bring such a dance in deliberately by importing it by link or ID — you will get its title, formation, and notes, and the review screen will tell you the figures were not available. ContraDB has no such restriction, so nothing is left out of a ContraDB search.

If the dance is already in your collection from an earlier import, the app tells you so and does not add a second copy — see Avoiding duplicates below.

If you already have a dance's web address — or even its number — you can import it directly:

  1. Open Settings, choose General, and choose Import….
  2. In the source selector, choose The Caller's Box or ContraDB.
  3. Paste the dance's web address — for The Caller's Box a dance.php?id=… link, for ContraDB a …/dances/N link — or enter its ID number (for example 1) in the address field, then choose Fetch. Paste a recognised address and the app selects the matching source for you.
  4. Review the dance and commit it, as described in Review before anything changes.

A few honest notes about these online imports:

  • They bring in one dance at a time and need an internet connection.
  • The app reads each archive's public dance page, so it depends on how that page is laid out; if a page changes or a dance has no figures listed, the dance still comes in with whatever the app could read (its title, formation, and notes), following the nothing gets lost promise above. This applies to the link-or-ID route described here — it is deliberately how you can still bring in a Caller's Box dance whose figures the Box will not share, even though online search leaves those out.
  • Figures come in as recognised moves where the app can read them and as plain-text figures otherwise, the same as every other import.
  • To have every dance you import on its own tagged automatically — a "no card" tag, say — choose the tags under Settings → Defaults → Import defaults. See Settings.

What the app will and won't fetch

Anything you paste is treated as untrusted, because a link can point anywhere. When you give the app a web address to fetch:

  • It must be https. A plain http address is refused rather than fetched over an unencrypted connection, and a redirect that tries to drop back to http is refused too.
  • It must be a real place on the internet. Addresses that point back at your own machine or your local network are turned away with That URL points to a network location that cannot be imported from.
  • It must belong to the source you chose. A Caller's Box import accepts links from ibiblio.org or www.ibiblio.org, under that site's /contradance/thecallersbox/ path — an ibiblio.org link outside that archive is not a Caller's Box link. A ContraDB import accepts links from contradb.com or www.contradb.com. Paste a link from anywhere else and you get a plain message naming what does work — or you can skip the link entirely and type the dance's ID number. This holds for the whole fetch, not just the address you typed: if an archive forwards the app somewhere else, that new address has to belong to the same source too, or the import stops there. A forward that leaves the source is turned away with the same general message as any other address the app won't fetch from, rather than one naming hosts — by that point the address came from the archive rather than from you, so there is nothing for you to retype.
  • Redirects and size are capped, so a link cannot bounce the app around indefinitely or hand it an endless download.

Refusals never echo the address back at you, so a link that happened to contain something private does not end up on your screen or in a log.

Import a published collection

Published collections are curated dance collections delivered through the trusted Compendium Analect catalog. They are signed and checked before the app offers them for import, and the app records their source and version so you can see where the dances came from.

  1. Open Collection and choose Import dances.
  2. Under the source selector, choose a published collection to review its title, version, dance count, and availability. You can also browse the same catalog from Settings → General → Published collections.
  3. Select Import collection and review what it contains.
  4. Confirm the import when you are ready. Nothing is added until you commit it, and the same review flow lets you skip items you do not want.

Bring in a list of dance titles

If you have a list of titles written down — an evening's set list, a workshop handout, dances a friend recommended — you can paste the whole list at once and let the app find them, without building a program.

  1. Open Collection and choose Import dances, or open Settings → General → Import….
  2. In the source selector, choose a list of titles.
  3. Paste your titles, one per line, and choose Review import.
  4. The app checks each title against your own collection first, then searches The Caller's Box for anything you don't already have.
  5. Review what it found and commit, as described in Review before anything changes.

Every title you pasted is listed on the review screen, grouped by what happened to it:

  • To import — the app found one dance with exactly that title. These get the usual review row, so you can look before you keep, change what each one does, or skip it.
  • Already in your collection — you have it. There is nothing to import, so the app tells you which dance it matched and who wrote it, since two different dances can share a title.
  • Not found — and it says which kind of "not found": the archive has no dance by that name, it only found near matches, several dances share that exact title so it can't tell which you meant, or it couldn't reach the archive just then. Those need different follow-up, so they are never lumped together.

A few honest notes:

  • The app only takes a dance when exactly one result matches your title exactly. Near matches are never imported on a guess.
  • The Caller's Box search it uses leaves out dances whose figures the Box will not share, so a title only held by one of those comes back as not found rather than arriving with no figures. You can still bring such a dance in deliberately by importing it by link or ID.
  • Nothing is written until you commit on the review screen, and an uncertain match is set to Skip by default, so a paste can never quietly duplicate something you already have.
  • Blank lines are ignored, and a title repeated in your list is only looked up once.
  • It works through the list one title at a time, showing its progress, and you can Cancel at any point — nothing has been added yet, so cancelling costs you nothing.
  • If the app can't reach The Caller's Box (you're offline, or the connection hangs), it stops after the first failure instead of trying every title, and says so once at the top of the review. The titles already in your collection are still listed; paste the rest again once you're online.
  • There is a limit of 100 titles per import. A longer list is refused outright rather than partly imported, so you are never left thinking a list came in whole when it didn't.
  • Even if nothing turns out to be importable, you still get the answer to "which of these do I already have?" — that list is worth having on its own.

Import a Caller's Compendium file

Dances shared as a Caller's Compendium file (the app's own .json format) come in through the same review flow:

  1. Open Settings, choose General, and choose Import….
  2. Set the source to a Caller's Compendium JSON file.
  3. Choose the file with Choose file…, paste its contents, or enter a URL and choose Fetch.
  4. Review and commit.

This is the format the app uses for sharing between callers and for the whole library backup described next. Importing a file adds to your collection through the review queue; it does not replace what you already have. To move an entire library and replace what is on a device, use Restore instead — see below.

A file made by a newer version of Caller's Compendium can still be reviewed and imported, but this version only understands the details it already knows about. The review then shows one warning, "This file was made by a newer version of Caller's Compendium. Update the app before importing, or some details may be left out." Update the app first if you want everything that file carries.

Open a shared program someone sent you

If another caller shares a program bundle with you — the Share (program + dances) file described in Share, print & export — you can often open the file directly:

  • Mac, iPhone, or iPad: open the .ccshare file wherever it arrives, or send it by AirDrop.
  • Android: open a .json bundle with Open with, or send it to the app from another app's Share menu.
  • Any device, including Linux and Windows: go to Settings › General and choose Import…, then pick the file.

Opened directly, the app launches and takes you straight to the same review screen a manual import uses, already loaded with what the file contains — the program, its dances, and its venue.

Nothing is added until you confirm. You review the bundle exactly as you would any other import, decide what to bring in, and commit; an Undo is offered afterwards.

This intake is deliberately safe. The file is treated as untrusted input: it is size-checked before being read, validated against the expected format, and a file that fails any check is turned away with a plain message and nothing is written. It is also identity-first — dances and programs you already have are matched and updated in place rather than duplicated, brand-new material is added, and nothing is ever deleted.

Bring your library across from Caller's Companion

Moving from Caller's Companion? Caller's Compendium can read its exported .USR library file and bring your material across in one pass:

  1. Open Settings, choose General, and choose Import….
  2. In the source selector, choose a Caller's Companion .USR file.
  3. Choose your .USR file when the app asks for it. Files over 256 MiB are refused; a typical Caller's Companion library is around 20 MB, far below that.
  4. Review and commit, as described in Review before anything changes.

A .USR import brings across both your dances and your program history (Caller's Companion "sets"), and — like every other import — it is reviewable before it commits and undoable right after. Dances and programs you have imported before are recognised and offered as updates rather than duplicated.

Your figures come across too. Caller's Companion keeps the actual choreography separately from the dance record, so earlier versions of the app brought your dances over with their titles, authors and notes but an empty body. The import now reads that choreography, so a migrated dance arrives with real A1/A2/B1/B2 figures you can search and edit. Anything the app cannot represent faithfully is kept word-for-word as text rather than guessed at.

Your venues and related-dance links come across as well. Set locations become real venue entries — matching one you already have when it is clearly the same place, and creating a new one when it isn't (an ambiguous match always creates a fresh venue rather than guessing). That happens when venue entities are switched on; with them off, the location is kept as plain text exactly as before. Dances that pointed at each other in Caller's Companion arrive linked as related dances.

If the .USR file is an incomplete copy — cut short by an interrupted download or copy — the review shows a warning above the list: "This file looks incomplete — only part of it could be read." Dances after the cut are missing, and the count of dances to import only reflects what could be read, so the warning is the sign that something is absent. Copy the file again from the original and import it again; dances you already imported are recognised and offered as updates rather than duplicated. The same warning area also tells you when figures, programs or related-dance links in the file could not be read.

One thing does not come across yet: custom glossary terms stay behind, because the app has no glossary of its own to put them in.

Bring your call buttons across as shorthands

If your Caller's Companion file has call buttons, the import offers to turn them into figure shorthands — short tokens you type during free-text entry that expand into whole figures.

The Seed figure shorthands screen lists the buttons it found and what each one would expand to. Tick the ones you want and choose the confirm button, which counts what you picked (Seed 3 shorthands), or choose Skip to move on. Nothing is added until you confirm.

Where a button offers two versions, you pick Primary or Alternate. And if a shorthand of that name already exists, the button is listed under Already defined — skipped and your existing one is left exactly as it is.

Move your whole library: backup and restore

A single Caller's Compendium file can hold everything — your dances, programs, custom fields, dialects, themes, and settings. This is how you keep a safety copy and how you move your whole library from an old machine to a new one. Because a backup you export can be restored (or imported) again exactly, moving between devices is a clean round trip: what you save is what you get back.

For step-by-step backup and restore, see Backup & portability. In short:

  • Export a backup — open Settings › General, find Export a backup, and choose Export. The app writes one .json file containing your entire collection, programs, custom fields, dialects, themes, and settings. Keep it somewhere safe or copy it to another device.
  • Restore from a backup — in the same section, choose Restore and pick a backup file. Restoring replaces everything currently in the app with the contents of the backup, so use it when you are setting up a device or recovering, not to merge two libraries. This cannot be undone, so the app asks you to confirm first.
  • Backup reminder — set a reminder cadence of Off, Weekly, or Monthly, and see when you last backed up, so a safety copy never drifts too far out of date.

Review before anything changes

Importing from a file or a URL opens the import review screen, and nothing touches your collection until you commit there — except Import and edit, which imports that one dance right away (and replaces the matched dance if the row is a Re-import or Link; you are asked first). It works the same whichever source you pick:

  1. Choose a source and give it something to read — pick the source, then add a file, paste text, or enter a URL or ID. (Paste a recognised web address and the app selects the matching source for you.)
  2. See the plan — the app reads the material without changing anything and lists every dance it found, with a sense of how much of each dance it could turn into structured figures versus keep as plain text, plus any notes about a particular dance.
  3. Decide dance by dance — each dance can be brought in as new, updated as a re-import of one you imported before, linked to an existing dance, kept as a separate duplicate, or skipped. Anything the app is unsure about defaults to skip, so it never guesses its way into your library. If something is wrong with the whole file — an incomplete .USR, or a file from a newer version of the app — a warning at the top of the list says so, and what to do about it.
  4. Commit — only now are the dances you accepted written to your collection.
  5. Undo — right after committing, the summary offers Undo, which removes everything the Import button added; dances brought in with Import and edit are not undone by it. This is the review-and-undo queue for bringing in more than one dance at a time.

The import review screen lists each dance and the action available for its current result, so you can inspect the batch before committing it.

The import review screen showing per-dance results with actions to import, edit, skip, or resolve each item

Avoiding duplicates

Re-importing the same dances should not clutter your collection, so the app watches for matches:

  • Same dance, same source. If you import a dance you have imported before from the same source, the app recognises it and offers to update the one you already have rather than adding a copy. (This is how the Caller's Box online import can tell you a dance "is already in your collection.")

  • Same dance, different source. If a dance matches one already in your collection by title, author, and figures — the same moves in the same order, even if the timing or notes differ — but comes from a different archive — the app prompts rather than adding a second copy. You can choose Same dance (update existing) to link the import to your existing copy — this replaces your version of the dance with the online record's, including its figures, notes, tags, rating, and custom fields; its place in your programs and its calling history are kept — Import a second copy to add it alongside your existing dance and keep both source records, or Cancel to leave your collection unchanged. This applies to single-dance online imports only; the batch review screen still marks the row for you to decide.

  • Looks like something you already have. If a dance closely matches one already in your collection by title and author but did not come from the same source, the review shows Possible match — choose how to import: and asks you to choose: Same dance — replace, keep both as a duplicate, or skip the new one. Same dance — replace keeps the existing dance's identity (its id, created date and history) but replaces its content with the imported version, including calling notes, rating, tags, custom fields, hook, walkthrough, status, links and source citations. The review warns how many existing dances will be overwritten before you commit.

  • Same name, different choreography. When the title and author match confidently but the figures differ, the app shows a Variation? block with an inline diff of exactly which lines changed, and offers Import as a variation — which keeps it as its own dance, optionally linked back to the original as a related dance — or Same dance — replace. Two dances that differ only in timing or in which figure carries the progression count as the same dance and never raise the prompt.

    For a single-dance online import (the Import button in the online preview), this same confirmation appears as a dialog rather than a review-screen block. The choices are identical: Import as a variation, Same dance (update existing), or Cancel. "Same dance" overwrites the existing dance with the incoming version — your edits, tags, and rating for the existing dance will be replaced — but your calling history is preserved.

Re-import an archive dance to pick up a correction

When the review screen recognises a dance you already imported, it offers Re-import onto that dance, naming the dance it would update, so there is no doubt which one it will touch. Choose it and the incoming version updates the dance you already have instead of adding a second copy, which is how you pick up a correction an archive has made since you first imported.

Dances already in your collection show Re-import and Skip choices in the review list, and Skip is the default, so choose Re-import on the ones you want updated. When many dances match, use Set all matched dances to: Re-import or Skip at the top of the list to change every one in a single tap (you can still change individual rows afterwards), and Skip all possible matches to skip every row marked as a possible match. The commit summary counts re-imports separately — Re-imported: 4 — so you can see at a glance how much of an import was new material and how much was an update. The Imported badge appears only on a row you brought in with Import and edit during review.

Re-importing overwrites that dance with the incoming version, so if you have edited your copy, look before you commit. The Undo on the summary reverses the whole batch import if it was not what you wanted (but not a dance you brought in with Import and edit).

Refresh choreography on one saved dance

From any saved dance detail view — including Collection, a Program Summary, global search, a post-import result, or a saved Program Editor preview — choose Re-import choreography. Select Caller's Box, ContraDB, or a Caller's Compendium JSON file. Online searches use the saved dance title and always show their results for you to choose from; the app never selects an online match automatically. JSON must contain exactly one dance and cannot contain a program.

Review the preview, then import to replace only the dance's figures, formation, and progression. This keeps your title, notes, rating, tags, links, custom fields, authors, citations, and other saved metadata. This is different from the normal import review's re-import/link choices, which can replace an entire imported record.

Importing whole programs

Everything above brings in dances. You can also import a whole program — a night's set list — in one go, and Caller's Compendium matches each dance to your collection (or imports it for you) as it reads the list:

  • From a plain-text list of dance titles you already have written down, and
  • From a ContraDB event, by pasting its link or searching for it by name.

Both live in the Import program menu on the Programs screen rather than the Import… flow here, because they build a program, not just add dances. For step-by-step instructions, see Programs & matrix › Import a program from ContraDB and Build from a list of titles.

If you want the dances but not a program, use Bring in a list of dance titles above instead.

Where to go next