The Tingdu wordset format

Version 1 · for your own words, phrases, pictures and sounds

A Tingdu wordset is one JSON file. Everything an item needs travels inside it: the text, its pronunciation, its translation and, if you like, a picture and a sound, written as data URLs (the binary file encoded as text). One file is all you share, back up or import: open Tingdu, tap Import, and choose the file or paste its text.

Prefer a spreadsheet? Tingdu also imports a simple CSV table. Want to start from something that works? Download the example wordset (nine words for a TV episode, with pictures).

The file at a glance

{
  "format": "tingdu-wordset",
  "version": 1,
  "wordset": {
    "id": "my-first-set",
    "name": "My first set",
    "language": "zh-CN",
    "items": [
      { "id": "w1", "text": "你好", "phonetic": "nǐ hǎo", "translation": "hello" }
    ]
  }
}

• format is always the string "tingdu-wordset".
• version is the number 1 (not the string "1").
• Then exactly one of: wordset, a single wordset object, or wordsets, an array of 1 to 500 wordset objects (this is what Tingdu writes when you export a whole collection).
• Other top-level fields are ignored.

Wordset fields

Item fields

A whole file may be up to 200 MB; above 20 MB Tingdu asks before importing, because it can be slow. Fields Tingdu does not know are ignored.

Pictures and sounds inside the JSON: data URLs

A data URL is a whole file written as text: data:, the file type, and the content. For a binary file (PNG, JPEG, WebP, MP3…) the content is base64:

data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA…
data:audio/mpeg;base64,SUQzBAAAAAAAI1RTU0UAAAAPAAADTGF2ZjU4…

Make one from a file with a single command and paste the result into the JSON:

Windows (PowerShell)

"data:image/png;base64," + [Convert]::ToBase64String([IO.File]::ReadAllBytes("$PWD\cat.png")) | Set-Clipboard

Linux

echo "data:audio/mpeg;base64,$(base64 -w0 cat.mp3)" > cat.txt

macOS

echo "data:audio/mpeg;base64,$(base64 -i cat.mp3)" | pbcopy

Or skip the commands: add pictures and recordings in Tingdu’s own editor and use Export. The exported file is this format, with every picture and sound already inside.

Pictures

• Allowed types: SVG (image/svg+xml), PNG, JPEG and WebP. A link such as https://…/cat.png is not accepted: the picture must be inside the file, so the wordset works offline.
• PNG, JPEG and WebP pictures larger than 256 px on their longer side are scaled down to 256 px (and stored as WebP) when you import, so big photos do not fill your device. SVG is kept as it is.
• SVG is the best choice for simple pictograms: tiny, sharp at every size, and easy to write by hand (or to ask an AI chat for). Use viewBox="0 0 64 64" and draw lines with stroke="currentColor", so they turn light in the dark theme. Tingdu removes <style>, style="…", <image>, <foreignObject>, links and scripts from an SVG before showing it; use plain attributes such as fill="#e4573d".
• An SVG can go in as base64, or as readable text with ;utf8,. In the text form use single quotes inside the SVG (the JSON string uses double quotes) and write # as %23:

"picture": "data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 64 64'><circle cx='32' cy='36' r='20' fill='%23e4573d' stroke='currentColor' stroke-width='3'/><path d='M32 16c0-6 4-8 8-8' fill='none' stroke='currentColor' stroke-width='3' stroke-linecap='round'/></svg>"

The same idea in base64 (a water drop):

"picture": "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA2NCA2NCI+PHBhdGggZD0iTTMyIDhDMjIgMjQgMTYgMzIgMTYgNDBhMTYgMTYgMCAwIDAgMzIgMGMwLTgtNi0xNi0xNi0zMnoiIGZpbGw9IiMzYTg2ZDQiIHN0cm9rZT0iY3VycmVudENvbG9yIiBzdHJva2Utd2lkdGg9IjMiIHN0cm9rZS1saW5lam9pbj0icm91bmQiLz48L3N2Zz4="

The picture games need enough pictures to choose from: at least 4 items with different pictures for Choose and Pairs, 6 for Rush.

Sounds (optional)

• You do not need sounds. An item without a sound is spoken by the device’s text-to-speech voice for the wordset’s language. Add a recording when you want a real voice, a particular accent, or a line from a scene.
• Any audio/… type is accepted; what plays depends on the device. MP3 (audio/mpeg) plays almost everywhere; audio/ogg, audio/webm and audio/mp4 are fine in current browsers and on Android.
• Keep recordings short: a word or a phrase, not a whole scene.

A complete example

Two pictured items and one without a picture. Copy it, paste it into the box on Tingdu’s Import page, tap Check pasted text, and it imports as it is. The example file is a longer one.

{
  "format": "tingdu-wordset",
  "version": 1,
  "wordset": {
    "id": "fruit-and-water",
    "name": "Fruit and water",
    "language": "zh-CN",
    "collection": "My first sets",
    "items": [
      {
        "id": "pingguo",
        "text": "苹果",
        "phonetic": "píngguǒ",
        "translation": "apple",
        "picture": "data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 64 64'><circle cx='32' cy='36' r='20' fill='%23e4573d' stroke='currentColor' stroke-width='3'/><path d='M32 16c0-6 4-8 8-8' fill='none' stroke='currentColor' stroke-width='3' stroke-linecap='round'/></svg>"
      },
      {
        "id": "shui",
        "text": "水",
        "phonetic": "shuǐ",
        "translation": "water",
        "picture": "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA2NCA2NCI+PHBhdGggZD0iTTMyIDhDMjIgMjQgMTYgMzIgMTYgNDBhMTYgMTYgMCAwIDAgMzIgMGMwLTgtNi0xNi0xNi0zMnoiIGZpbGw9IiMzYTg2ZDQiIHN0cm9rZT0iY3VycmVudENvbG9yIiBzdHJva2Utd2lkdGg9IjMiIHN0cm9rZS1saW5lam9pbj0icm91bmQiLz48L3N2Zz4="
      },
      {
        "id": "ni-hao",
        "text": "你好",
        "phonetic": "nǐ hǎo",
        "translation": "hello",
        "extra": { "note": "the first word of every series" }
      }
    ]
  }
}

An item with its own recording looks the same, with one more field (shortened here):

{ "id": "xie-xie", "text": "谢谢", "phonetic": "xièxie", "translation": "thank you",
  "sound": "data:audio/mpeg;base64,SUQzBAAAAAAAI1RTU0UAAAAPAAADTGF2ZjU4…" }

The CSV alternative

A table saved as CSV from a spreadsheet works too, one item per row. The first row names the columns:

text,phonetic,translation
咖啡,kāfēi,coffee
手机,shǒujī,mobile phone
"没关系",méi guānxi,"it's fine, no problem"

• Columns: text and translation are required; phonetic, picture and sound are optional. Names are not case-sensitive, any order works, and other columns are ignored.
• Standard CSV quoting: a cell with a comma, a quote or a line break goes in double quotes, and a quote inside it is doubled (""). A data URL always contains a comma, so a picture or sound cell must be quoted.
• Spaces around a cell are trimmed; empty rows are skipped; a byte order mark is fine; line ends may be LF or CR LF.
• The wordset’s name is the file name (or “My wordset” for pasted text) and its language is guessed: Chinese (zh-CN) when at least half of the texts contain Chinese characters, otherwise English (en-US). You can change both before saving. Item ids are numbered for you.
• Errors name the row, counting the header as row 1: row 4.text.

When the import says “The file is not valid”

Tingdu checks the whole file before it saves anything and lists the first ten problems, each with where it is: wordset.items[3].text is the text of the fourth item (counting from 0).

Making a list for a TV series with an AI chat? The blog post Learn Chinese with the TV series you love has a ready-to-copy prompt that asks for exactly this format.