@@ -667,8 +667,8 @@ ENVEOF
fi
# ── Caddy + Authelia-aware protection ────────────────────────────────────
- # This dashboard shows every family member's personal study activity —
- # same "sensitive, protect by default" reasoning as
+ # This dashboard shows every account's personal study activity — same
+ # "sensitive, protect by default" reasoning as
# services/security-dashboard.sh: auto-use local Authelia if present, no
# prompt needed; otherwise warn clearly and offer a remote instance,
# since leaving it open is a real privacy tradeoff, not a neutral default.
@@ -677,9 +677,9 @@ ENVEOF
EXTRA_BLOCK=" import authelia"
log_info "Local Authelia detected — protecting with it."
else
- log_warning "No local Authelia found. This dashboard shows every family"
- log_warning "member's personal study activity — recommend protecting it"
- log_warning "before exposing it publicly."
+ log_warning "No local Authelia found. This dashboard shows every account's"
+ log_warning "personal study activity — recommend protecting it before"
+ log_warning "exposing it publicly."
local _use_remote=""
prompt_yn " Protect with a remote Authelia instance (e.g. on a homelab)? (y/n):" "y" _use_remote
if [[ "$_use_remote" =~ ^[Yy]$ ]]; then
diff --git a/tools/anki-deck-math.py b/tools/anki-deck-math.py
new file mode 100644
index 0000000..4413089
--- /dev/null
+++ b/tools/anki-deck-math.py
@@ -0,0 +1,420 @@
+#!/usr/bin/env python3
+"""tools/anki-deck-math.py — Generate math-fact Anki decks (.apkg) with a
+vertical/stacked problem layout, Anki's built-in type-the-answer input, and
+Piper (offline, local neural TTS) audio on both the question and answer
+side of every card.
+
+Standalone content-generation tool, unrelated to this repo's services/*.sh
+installers — run it on any machine with Python (your desktop, laptop, or
+the same box running services/anki-sync-server.sh), then import the
+resulting .apkg into Anki (File -> Import) or push it into a sync-server
+account with AnkiConnect's importPackage action. See services/anki-sync-server.sh
+and services/anki-progress.sh for the actual self-hosted sync backend and
+progress dashboard this content is meant to be studied through.
+
+Decks:
+ multiplication 1-12, all 144 ordered pairs (a x b), shuffled
+ (not sequential — see the note near
+ random.shuffle(pairs) below for why)
+ division inverse of the multiplication deck (144 facts)
+ addsub --lo L --hi H addition + subtraction fact family for [L, H]
+ (subtraction facts derived from the addition
+ facts, e.g. 7+3=10 also gives 10-7=3 and
+ 10-3=7 — never negative results)
+ fractions reducing fractions to lowest terms (denominators 2-12)
+ decimals fraction -> decimal conversion (only denominators
+ whose decimal expansion terminates: 2,4,5,8,10,20,25)
+
+Setup (one time):
+ python3 -m venv ~/anki-deck-venv
+ source ~/anki-deck-venv/bin/activate
+ pip install genanki piper-tts
+
+ # Download at least one voice (one time per voice you want to try —
+ # download_voices saves into the CURRENT directory by default, so cd
+ # somewhere sensible first, e.g. your home directory):
+ python3 -m piper.download_voices en_US-lessac-medium
+ # Other options: en_US-amy-medium (warm/friendly), en_US-ryan-high
+ # (best-quality US male), en_US-libritts_r-medium (multi-speaker),
+ # en_GB-alba-medium / en_GB-cori-high (British accent). Tiers are
+ # low < medium < high — higher sounds more natural but is bigger/slower.
+
+ # Sanity-check the voice before generating a full deck's worth of clips:
+ echo "three times seven" | python3 -m piper -m en_US-lessac-medium.onnx -f /tmp/test.wav
+ # play /tmp/test.wav and confirm it sounds right first.
+
+Usage (run with the venv activated):
+ python3 anki-deck-math.py --deck multiplication
+ python3 anki-deck-math.py --deck division
+ python3 anki-deck-math.py --deck addsub --lo 3 --hi 7
+ python3 anki-deck-math.py --deck addsub --lo 3 --hi 13
+ python3 anki-deck-math.py --deck addsub --lo 2 --hi 21
+ python3 anki-deck-math.py --deck fractions
+ python3 anki-deck-math.py --deck decimals
+(add --voice en_US-amy-medium etc. to any of the above to use a voice other
+than the default en_US-lessac-medium; --model-path to point at a voice
+file directly if it's not found in any of the usual places checked
+automatically; --dry-run-tts to test the deck-building logic itself
+without Piper or any voice model at all, using silent placeholder audio)
+
+The addsub --hi 21 deck generates ~1600 audio clips and will take noticeably
+longer than the others — consider `nohup python3 anki-deck-math.py --deck
+addsub --lo 2 --hi 21 > addsub.log 2>&1 &` if you don't want to wait on it.
+"""
+import argparse
+import hashlib
+import genanki
+import math
+import os
+import random
+import subprocess
+
+parser = argparse.ArgumentParser()
+parser.add_argument("--deck", required=True,
+ choices=["multiplication", "division", "addsub", "fractions", "decimals"])
+parser.add_argument("--lo", type=int, default=None, help="addsub only: low end of range")
+parser.add_argument("--hi", type=int, default=None, help="addsub only: high end of range")
+parser.add_argument("--voice", default="en_US-lessac-medium")
+parser.add_argument("--model-path", default=None)
+parser.add_argument("--dry-run-tts", action="store_true",
+ help="Skip Piper entirely and write silent placeholder audio instead"
+ " (for testing the deck-building logic without a voice model).")
+args = parser.parse_args()
+
+if args.deck == "addsub":
+ if args.lo is None or args.hi is None:
+ raise SystemExit("--deck addsub requires --lo and --hi, e.g. --lo 3 --hi 7")
+ if args.lo >= args.hi:
+ raise SystemExit("--lo must be less than --hi")
+
+SCRATCH = os.path.dirname(os.path.abspath(__file__))
+
+# ─── Voice resolution (same search order as the multiplication script) ──────
+_CANDIDATES = [
+ args.model_path,
+ f"{args.voice}.onnx",
+ os.path.join(SCRATCH, f"{args.voice}.onnx"),
+ os.path.expanduser(f"~/{args.voice}.onnx"),
+ os.path.expanduser(f"~/.local/share/piper/voices/{args.voice}.onnx"),
+]
+VOICE_MODEL = next((p for p in _CANDIDATES if p and os.path.isfile(p)), None)
+
+if VOICE_MODEL is None and not args.dry_run_tts:
+ raise SystemExit(
+ f"Voice model for '{args.voice}' not found. Checked:\n"
+ + "\n".join(f" {p}" for p in _CANDIDATES if p)
+ + f"\n\nFind it with: find / -iname '{args.voice}.onnx' 2>/dev/null"
+ + "\nThen pass its exact path with --model-path /the/real/path.onnx"
+ + "\n(or pass --dry-run-tts to test deck-building without any voice at all)"
+ )
+
+
+def piper_tts(text: str, out_path: str) -> None:
+ if args.dry_run_tts:
+ # 44-byte minimal valid WAV header, zero samples — enough for genanki
+ # to accept it as a real media file without needing Piper installed.
+ with open(out_path, "wb") as f:
+ f.write(
+ b"RIFF$\x00\x00\x00WAVEfmt \x10\x00\x00\x00\x01\x00\x01\x00"
+ b"\x22\x56\x00\x00\x44\xac\x00\x00\x02\x00\x10\x00data\x00\x00\x00\x00"
+ )
+ return
+ subprocess.run(
+ ["python3", "-m", "piper", "-m", VOICE_MODEL, "-f", out_path],
+ input=text.encode("utf-8"),
+ check=True,
+ capture_output=True,
+ )
+
+
+# ─── Number -> words ─────────────────────────────────────────────────────────
+ONES = ["zero", "one", "two", "three", "four", "five", "six", "seven",
+ "eight", "nine", "ten", "eleven", "twelve", "thirteen", "fourteen",
+ "fifteen", "sixteen", "seventeen", "eighteen", "nineteen"]
+TENS = ["", "", "twenty", "thirty", "forty", "fifty", "sixty", "seventy",
+ "eighty", "ninety"]
+
+
+def num2words(n):
+ if n < 0:
+ return "negative " + num2words(-n)
+ if n < 20:
+ return ONES[n]
+ if n < 100:
+ t, o = divmod(n, 10)
+ return TENS[t] + ("-" + ONES[o] if o else "")
+ h, rem = divmod(n, 100)
+ return ONES[h] + " hundred" + (" " + num2words(rem) if rem else "")
+
+
+_NUM_CHECKS = {0: "zero", 9: "nine", 10: "ten", 13: "thirteen", 20: "twenty",
+ 21: "twenty-one", 45: "forty-five", 99: "ninety-nine",
+ 100: "one hundred", 110: "one hundred ten",
+ 121: "one hundred twenty-one", 144: "one hundred forty-four",
+ 441: "four hundred forty-one"}
+for _n, _w in _NUM_CHECKS.items():
+ assert num2words(_n) == _w, f"num2words({_n}) = {num2words(_n)!r}, expected {_w!r}"
+
+# Ordinal words, singular form, denominators 2-21 (covers every deck below).
+# Irregular forms (half, third, fifth, eighth, ninth, twelfth) are real
+# English irregularities, not a suffix rule, so this is a lookup table, not
+# a formula — a formula would get exactly these wrong.
+ORDINAL_SINGULAR = {
+ 2: "half", 3: "third", 4: "fourth", 5: "fifth", 6: "sixth",
+ 7: "seventh", 8: "eighth", 9: "ninth", 10: "tenth", 11: "eleventh",
+ 12: "twelfth", 13: "thirteenth", 14: "fourteenth", 15: "fifteenth",
+ 16: "sixteenth", 17: "seventeenth", 18: "eighteenth", 19: "nineteenth",
+ 20: "twentieth", 21: "twenty-first", 25: "twenty-fifth", 50: "fiftieth",
+ 100: "hundredth",
+}
+
+
+def ordinal_plural(n):
+ s = ORDINAL_SINGULAR[n]
+ return "halves" if s == "half" else s + "s"
+
+
+def fraction_words(num, den):
+ """'three fourths', 'one half', 'seven tenths'."""
+ ord_word = ORDINAL_SINGULAR[den] if num == 1 else ordinal_plural(den)
+ return f"{num2words(num)} {ord_word}"
+
+
+_FRAC_CHECKS = {
+ (1, 2): "one half", (3, 4): "three fourths", (1, 4): "one fourth",
+ (7, 10): "seven tenths", (1, 3): "one third", (2, 3): "two thirds",
+ (5, 8): "five eighths", (1, 8): "one eighth",
+}
+for (_n, _d), _w in _FRAC_CHECKS.items():
+ assert fraction_words(_n, _d) == _w, f"fraction_words({_n},{_d}) = {fraction_words(_n, _d)!r}, expected {_w!r}"
+
+
+def decimal_words(decimal_str):
+ """'0.25' -> 'zero point two five' (each digit spoken individually,
+ avoids any ambiguity between e.g. 'point two five' vs 'twenty-five
+ hundredths')."""
+ whole, frac = decimal_str.split(".")
+ digit_words = " ".join(ONES[int(d)] for d in frac)
+ return f"{num2words(int(whole))} point {digit_words}"
+
+
+assert decimal_words("0.25") == "zero point two five"
+assert decimal_words("0.5") == "zero point five"
+assert decimal_words("0.375") == "zero point three seven five"
+
+
+# ─── Shared genanki model builder ────────────────────────────────────────────
+# Every deck here renders as two stacked lines with a line under them (same
+# visual language as the original multiplication deck): TOP over BOTTOM,
+# with an optional prefix (operator) on the bottom line. Fractions/decimals
+# reuse the exact same layout as numerator-over-denominator.
+def build_model(deck_key):
+ voice_hash = int(hashlib.sha256(f"{deck_key}:{args.voice}".encode()).hexdigest(), 16)
+ model_id = 1_600_000_000 + (voice_hash % 90_000_000)
+ return model_id, genanki.Model(
+ model_id,
+ f"Math Fact ({deck_key}, {args.voice})",
+ fields=[{"name": "Top"}, {"name": "Bottom"}, {"name": "Answer"},
+ {"name": "QSound"}, {"name": "ASound"}],
+ templates=[{
+ "name": "Card",
+ "qfmt": """
+
+{{type:Answer}} +{{ASound}} +""", + }], + css=""" +.card { font-family: Arial, sans-serif; font-size: 28px; text-align: center; } +.problem { display: inline-block; text-align: right; margin: 20px auto; } +.line1, .line2 { font-size: 48px; padding: 2px 10px; } +.rule { border-top: 3px solid black; margin-top: 4px; width: 100%; } +""", + ) + + +def build_deck(deck_key, deck_title): + voice_hash = int(hashlib.sha256(f"{deck_key}:{args.voice}".encode()).hexdigest(), 16) + deck_id = 2_000_000_000 + (voice_hash % 90_000_000) + return genanki.Deck(deck_id, deck_title) + + +def add_note(deck, model, top, bottom, answer, qtext, atext, media_files, tag): + qfile = f"q_{tag}.wav" + afile = f"a_{tag}.wav" + qpath = os.path.join(MEDIA_DIR, qfile) + apath = os.path.join(MEDIA_DIR, afile) + piper_tts(qtext, qpath) + piper_tts(atext, apath) + media_files += [qpath, apath] + deck.add_note(genanki.Note( + model=model, + fields=[top, bottom, answer, f"[sound:{qfile}]", f"[sound:{afile}]"], + )) + + +# ─── Per-deck generators ───────────────────────────────────────────────────── +def gen_multiplication(): + deck_key = "multiplication" + model_id, model = build_model(deck_key) + deck = build_deck(deck_key, "Multiplication Facts (1-12)") + media_files = [] + pairs = [(a, b) for a in range(1, 13) for b in range(1, 13)] + random.seed(42) + random.shuffle(pairs) + for a, b in pairs: + ans = a * b + add_note(deck, model, str(a), f"× {b}", str(ans), + f"{num2words(a)} times {num2words(b)}", num2words(ans), + media_files, f"mul_{a}_{b}") + return deck, media_files, len(pairs) + + +def gen_division(): + deck_key = "division" + model_id, model = build_model(deck_key) + deck = build_deck(deck_key, "Division Facts (inverse of 1-12 times tables)") + media_files = [] + # Same (a, b) pairs as multiplication: product / a = b. This is the + # direct inverse of every multiplication card in that deck. + pairs = [(a, b) for a in range(1, 13) for b in range(1, 13)] + random.seed(43) + random.shuffle(pairs) + for a, b in pairs: + product = a * b + add_note(deck, model, str(product), f"÷ {a}", str(b), + f"{num2words(product)} divided by {num2words(a)}", num2words(b), + media_files, f"div_{a}_{b}") + return deck, media_files, len(pairs) + + +def gen_addsub(lo, hi): + deck_key = f"addsub_{lo}_{hi}" + model_id, model = build_model(deck_key) + deck = build_deck(deck_key, f"Addition & Subtraction Facts ({lo}-{hi})") + media_files = [] + + add_pairs = [(a, b) for a in range(lo, hi + 1) for b in range(lo, hi + 1)] + random.seed(hash((lo, hi)) & 0xFFFFFFFF) + random.shuffle(add_pairs) + + sub_facts = [] # (minuend, subtrahend, answer) + seen = set() + for a, b in add_pairs: + c = a + b + for minuend, subtrahend, answer in ((c, a, b), (c, b, a)): + key = (minuend, subtrahend) + if key not in seen: + seen.add(key) + sub_facts.append((minuend, subtrahend, answer)) + random.shuffle(sub_facts) + + count = 0 + for a, b in add_pairs: + ans = a + b + add_note(deck, model, str(a), f"+ {b}", str(ans), + f"{num2words(a)} plus {num2words(b)}", num2words(ans), + media_files, f"add_{lo}_{hi}_{a}_{b}") + count += 1 + for minuend, subtrahend, answer in sub_facts: + add_note(deck, model, str(minuend), f"− {subtrahend}", str(answer), + f"{num2words(minuend)} minus {num2words(subtrahend)}", num2words(answer), + media_files, f"sub_{lo}_{hi}_{minuend}_{subtrahend}") + count += 1 + return deck, media_files, count + + +def gen_fractions(): + deck_key = "fractions" + model_id, model = build_model(deck_key) + deck = build_deck(deck_key, "Reducing Fractions to Lowest Terms") + media_files = [] + + facts = [] + for den in range(2, 13): + for num in range(1, den): + g = math.gcd(num, den) + if g > 1: + facts.append((num, den, num // g, den // g)) + random.seed(44) + random.shuffle(facts) + + for num, den, rnum, rden in facts: + answer = f"{rnum}/{rden}" + add_note(deck, model, str(num), f"⁄ {den}", answer, + fraction_words(num, den), fraction_words(rnum, rden), + media_files, f"frac_{num}_{den}") + return deck, media_files, len(facts) + + +def gen_decimals(): + deck_key = "decimals" + model_id, model = build_model(deck_key) + deck = build_deck(deck_key, "Fraction to Decimal Conversion") + media_files = [] + + # Only denominators whose only prime factors are 2 and 5 terminate in a + # finite decimal (1/3 = 0.333... never terminates) — restricting to + # these avoids ever needing to round/repeat. + facts = [] + for den in (2, 4, 5, 8, 10, 20, 25): + for num in range(1, den): + if math.gcd(num, den) != 1: + continue # skip non-lowest-terms fractions (already covered by the fractions deck) + value = num / den + decimal_str = f"{value:.10f}".rstrip("0") + if decimal_str.endswith("."): + decimal_str += "0" + facts.append((num, den, decimal_str)) + random.seed(45) + random.shuffle(facts) + + for num, den, decimal_str in facts: + add_note(deck, model, str(num), f"⁄ {den}", decimal_str, + fraction_words(num, den), decimal_words(decimal_str), + media_files, f"dec_{num}_{den}") + return deck, media_files, len(facts) + + +# ─── Dispatch ───────────────────────────────────────────────────────────────── +if args.deck == "addsub": + deck_key = f"addsub_{args.lo}_{args.hi}" +else: + deck_key = args.deck + +MEDIA_DIR = os.path.join(SCRATCH, f"media_{deck_key}_{args.voice}") +os.makedirs(MEDIA_DIR, exist_ok=True) + +GENERATORS = { + "multiplication": lambda: gen_multiplication(), + "division": lambda: gen_division(), + "addsub": lambda: gen_addsub(args.lo, args.hi), + "fractions": lambda: gen_fractions(), + "decimals": lambda: gen_decimals(), +} + +deck, media_files, count = GENERATORS[args.deck]() +if count == 0: + raise SystemExit(f"No cards generated for --deck {args.deck} — check the range/args.") + +package = genanki.Package(deck) +package.media_files = media_files +out_path = os.path.join(SCRATCH, f"{deck_key}_{args.voice}.apkg") +package.write_to_file(out_path) + +size_mb = os.path.getsize(out_path) / (1024 * 1024) +print(f"\nDone: {out_path} ({size_mb:.1f} MB, {count} cards, {len(media_files)} audio clips)") diff --git a/tools/anki-deck-periodic.py b/tools/anki-deck-periodic.py new file mode 100644 index 0000000..784c6cb --- /dev/null +++ b/tools/anki-deck-periodic.py @@ -0,0 +1,385 @@ +#!/usr/bin/env python3 +"""tools/anki-deck-periodic.py — Generate periodic table Anki decks (.apkg) +with Anki's built-in type-the-answer input and Piper (offline, local +neural TTS) audio on both sides. See tools/anki-deck-math.py's docstring +for one-time setup (venv, genanki + piper-tts, downloading a voice) — same +steps apply here, this is a standalone, self-contained script otherwise. + +Decks: + prehs symbol<->name, elements 1-36 (H through Kr) + hs symbol<->name plus number->symbol, all 118 elements + category element category as multiple choice (A/B/C/D shown as + plain text options — not a clickable UI, since that needs + a desktop-only Anki add-on and would break on + AnkiDroid/AnkiMobile), type the letter — only elements + with a confirmed category (excludes 8 very recent + superheavy elements whose category is still officially + unconfirmed) + +Element data: Bowserinator/Periodic-Table-JSON (a widely used, actively +maintained public dataset), fetched and spot-checked against known facts +before being embedded below — not typed from memory. + +Usage (run with the venv from anki-deck-math.py's docstring activated): + python3 anki-deck-periodic.py --deck prehs + python3 anki-deck-periodic.py --deck hs + python3 anki-deck-periodic.py --deck category +(add --voice en_US-amy-medium etc.; --model-path if a voice isn't found +automatically; --dry-run-tts to test the deck-building logic without any +voice model at all, using silent placeholder audio) +""" +import argparse +import hashlib +import genanki +import os +import random +import subprocess + +parser = argparse.ArgumentParser() +parser.add_argument("--deck", required=True, choices=["prehs", "hs", "category"]) +parser.add_argument("--voice", default="en_US-lessac-medium") +parser.add_argument("--model-path", default=None) +parser.add_argument("--dry-run-tts", action="store_true") +args = parser.parse_args() + +SCRATCH = os.path.dirname(os.path.abspath(__file__)) + +_CANDIDATES = [ + args.model_path, + f"{args.voice}.onnx", + os.path.join(SCRATCH, f"{args.voice}.onnx"), + os.path.expanduser(f"~/{args.voice}.onnx"), + os.path.expanduser(f"~/.local/share/piper/voices/{args.voice}.onnx"), +] +VOICE_MODEL = next((p for p in _CANDIDATES if p and os.path.isfile(p)), None) + +if VOICE_MODEL is None and not args.dry_run_tts: + raise SystemExit( + f"Voice model for '{args.voice}' not found. Checked:\n" + + "\n".join(f" {p}" for p in _CANDIDATES if p) + + f"\n\nFind it with: find / -iname '{args.voice}.onnx' 2>/dev/null" + + "\nThen pass its exact path with --model-path /the/real/path.onnx" + + "\n(or pass --dry-run-tts to test deck-building without any voice at all)" + ) + + +def piper_tts(text: str, out_path: str) -> None: + if args.dry_run_tts: + with open(out_path, "wb") as f: + f.write( + b"RIFF$\x00\x00\x00WAVEfmt \x10\x00\x00\x00\x01\x00\x01\x00" + b"\x22\x56\x00\x00\x44\xac\x00\x00\x02\x00\x10\x00data\x00\x00\x00\x00" + ) + return + subprocess.run( + ["python3", "-m", "piper", "-m", VOICE_MODEL, "-f", out_path], + input=text.encode("utf-8"), + check=True, + capture_output=True, + ) + + +ONES = ["zero", "one", "two", "three", "four", "five", "six", "seven", + "eight", "nine", "ten", "eleven", "twelve", "thirteen", "fourteen", + "fifteen", "sixteen", "seventeen", "eighteen", "nineteen"] +TENS = ["", "", "twenty", "thirty", "forty", "fifty", "sixty", "seventy", + "eighty", "ninety"] + + +def num2words(n): + if n < 20: + return ONES[n] + if n < 100: + t, o = divmod(n, 10) + return TENS[t] + ("-" + ONES[o] if o else "") + h, rem = divmod(n, 100) + return ONES[h] + " hundred" + (" " + num2words(rem) if rem else "") + + +assert num2words(1) == "one" +assert num2words(26) == "twenty-six" +assert num2words(118) == "one hundred eighteen" + +# ─── Element data: (atomic_number, symbol, name, category-or-None) ───────── +# category is None for the 8 most recently synthesized superheavy elements +# whose chemical category is still officially unconfirmed (excluded from +# the category deck below, still included in prehs/hs symbol/name/number). +ELEMENTS = [ + (1, 'H', 'Hydrogen', 'diatomic nonmetal'), + (2, 'He', 'Helium', 'noble gas'), + (3, 'Li', 'Lithium', 'alkali metal'), + (4, 'Be', 'Beryllium', 'alkaline earth metal'), + (5, 'B', 'Boron', 'metalloid'), + (6, 'C', 'Carbon', 'polyatomic nonmetal'), + (7, 'N', 'Nitrogen', 'diatomic nonmetal'), + (8, 'O', 'Oxygen', 'diatomic nonmetal'), + (9, 'F', 'Fluorine', 'diatomic nonmetal'), + (10, 'Ne', 'Neon', 'noble gas'), + (11, 'Na', 'Sodium', 'alkali metal'), + (12, 'Mg', 'Magnesium', 'alkaline earth metal'), + (13, 'Al', 'Aluminium', 'post-transition metal'), + (14, 'Si', 'Silicon', 'metalloid'), + (15, 'P', 'Phosphorus', 'polyatomic nonmetal'), + (16, 'S', 'Sulfur', 'polyatomic nonmetal'), + (17, 'Cl', 'Chlorine', 'diatomic nonmetal'), + (18, 'Ar', 'Argon', 'noble gas'), + (19, 'K', 'Potassium', 'alkali metal'), + (20, 'Ca', 'Calcium', 'alkaline earth metal'), + (21, 'Sc', 'Scandium', 'transition metal'), + (22, 'Ti', 'Titanium', 'transition metal'), + (23, 'V', 'Vanadium', 'transition metal'), + (24, 'Cr', 'Chromium', 'transition metal'), + (25, 'Mn', 'Manganese', 'transition metal'), + (26, 'Fe', 'Iron', 'transition metal'), + (27, 'Co', 'Cobalt', 'transition metal'), + (28, 'Ni', 'Nickel', 'transition metal'), + (29, 'Cu', 'Copper', 'transition metal'), + (30, 'Zn', 'Zinc', 'transition metal'), + (31, 'Ga', 'Gallium', 'post-transition metal'), + (32, 'Ge', 'Germanium', 'metalloid'), + (33, 'As', 'Arsenic', 'metalloid'), + (34, 'Se', 'Selenium', 'polyatomic nonmetal'), + (35, 'Br', 'Bromine', 'diatomic nonmetal'), + (36, 'Kr', 'Krypton', 'noble gas'), + (37, 'Rb', 'Rubidium', 'alkali metal'), + (38, 'Sr', 'Strontium', 'alkaline earth metal'), + (39, 'Y', 'Yttrium', 'transition metal'), + (40, 'Zr', 'Zirconium', 'transition metal'), + (41, 'Nb', 'Niobium', 'transition metal'), + (42, 'Mo', 'Molybdenum', 'transition metal'), + (43, 'Tc', 'Technetium', 'transition metal'), + (44, 'Ru', 'Ruthenium', 'transition metal'), + (45, 'Rh', 'Rhodium', 'transition metal'), + (46, 'Pd', 'Palladium', 'transition metal'), + (47, 'Ag', 'Silver', 'transition metal'), + (48, 'Cd', 'Cadmium', 'transition metal'), + (49, 'In', 'Indium', 'post-transition metal'), + (50, 'Sn', 'Tin', 'post-transition metal'), + (51, 'Sb', 'Antimony', 'metalloid'), + (52, 'Te', 'Tellurium', 'metalloid'), + (53, 'I', 'Iodine', 'diatomic nonmetal'), + (54, 'Xe', 'Xenon', 'noble gas'), + (55, 'Cs', 'Cesium', 'alkali metal'), + (56, 'Ba', 'Barium', 'alkaline earth metal'), + (57, 'La', 'Lanthanum', 'lanthanide'), + (58, 'Ce', 'Cerium', 'lanthanide'), + (59, 'Pr', 'Praseodymium', 'lanthanide'), + (60, 'Nd', 'Neodymium', 'lanthanide'), + (61, 'Pm', 'Promethium', 'lanthanide'), + (62, 'Sm', 'Samarium', 'lanthanide'), + (63, 'Eu', 'Europium', 'lanthanide'), + (64, 'Gd', 'Gadolinium', 'lanthanide'), + (65, 'Tb', 'Terbium', 'lanthanide'), + (66, 'Dy', 'Dysprosium', 'lanthanide'), + (67, 'Ho', 'Holmium', 'lanthanide'), + (68, 'Er', 'Erbium', 'lanthanide'), + (69, 'Tm', 'Thulium', 'lanthanide'), + (70, 'Yb', 'Ytterbium', 'lanthanide'), + (71, 'Lu', 'Lutetium', 'lanthanide'), + (72, 'Hf', 'Hafnium', 'transition metal'), + (73, 'Ta', 'Tantalum', 'transition metal'), + (74, 'W', 'Tungsten', 'transition metal'), + (75, 'Re', 'Rhenium', 'transition metal'), + (76, 'Os', 'Osmium', 'transition metal'), + (77, 'Ir', 'Iridium', 'transition metal'), + (78, 'Pt', 'Platinum', 'transition metal'), + (79, 'Au', 'Gold', 'transition metal'), + (80, 'Hg', 'Mercury', 'transition metal'), + (81, 'Tl', 'Thallium', 'post-transition metal'), + (82, 'Pb', 'Lead', 'post-transition metal'), + (83, 'Bi', 'Bismuth', 'post-transition metal'), + (84, 'Po', 'Polonium', 'post-transition metal'), + (85, 'At', 'Astatine', 'diatomic nonmetal'), + (86, 'Rn', 'Radon', 'noble gas'), + (87, 'Fr', 'Francium', 'alkali metal'), + (88, 'Ra', 'Radium', 'alkaline earth metal'), + (89, 'Ac', 'Actinium', 'actinide'), + (90, 'Th', 'Thorium', 'actinide'), + (91, 'Pa', 'Protactinium', 'actinide'), + (92, 'U', 'Uranium', 'actinide'), + (93, 'Np', 'Neptunium', 'actinide'), + (94, 'Pu', 'Plutonium', 'actinide'), + (95, 'Am', 'Americium', 'actinide'), + (96, 'Cm', 'Curium', 'actinide'), + (97, 'Bk', 'Berkelium', 'actinide'), + (98, 'Cf', 'Californium', 'actinide'), + (99, 'Es', 'Einsteinium', 'actinide'), + (100, 'Fm', 'Fermium', 'actinide'), + (101, 'Md', 'Mendelevium', 'actinide'), + (102, 'No', 'Nobelium', 'actinide'), + (103, 'Lr', 'Lawrencium', 'actinide'), + (104, 'Rf', 'Rutherfordium', 'transition metal'), + (105, 'Db', 'Dubnium', 'transition metal'), + (106, 'Sg', 'Seaborgium', 'transition metal'), + (107, 'Bh', 'Bohrium', 'transition metal'), + (108, 'Hs', 'Hassium', 'transition metal'), + (109, 'Mt', 'Meitnerium', None), + (110, 'Ds', 'Darmstadtium', None), + (111, 'Rg', 'Roentgenium', None), + (112, 'Cn', 'Copernicium', None), + (113, 'Nh', 'Nihonium', 'post-transition metal'), + (114, 'Fl', 'Flerovium', 'post-transition metal'), + (115, 'Mc', 'Moscovium', None), + (116, 'Lv', 'Livermorium', None), + (117, 'Ts', 'Tennessine', None), + (118, 'Og', 'Oganesson', None), +] +assert len(ELEMENTS) == 118 +assert [e[0] for e in ELEMENTS] == list(range(1, 119)) +assert ELEMENTS[0] == (1, 'H', 'Hydrogen', 'diatomic nonmetal') +assert ELEMENTS[25] == (26, 'Fe', 'Iron', 'transition metal') +assert ELEMENTS[-1] == (118, 'Og', 'Oganesson', None) + +ALL_CATEGORIES = sorted({e[3] for e in ELEMENTS if e[3] is not None}) + + +def build_model(deck_key): + voice_hash = int(hashlib.sha256(f"{deck_key}:{args.voice}".encode()).hexdigest(), 16) + model_id = 1_700_000_000 + (voice_hash % 90_000_000) + return model_id, genanki.Model( + model_id, + f"Periodic Table ({deck_key}, {args.voice})", + fields=[{"name": "Prompt"}, {"name": "Answer"}, {"name": "QSound"}, {"name": "ASound"}], + templates=[{ + "name": "Card", + "qfmt": """ +
+{{type:Answer}} +{{ASound}} +""", + }], + css=""" +.card { font-family: Arial, sans-serif; font-size: 26px; text-align: center; } +.prompt { font-size: 40px; margin: 20px auto; white-space: pre-line; } +""", + ) + + +def build_deck(deck_key, deck_title): + voice_hash = int(hashlib.sha256(f"{deck_key}:{args.voice}".encode()).hexdigest(), 16) + deck_id = 2_100_000_000 + (voice_hash % 90_000_000) + return genanki.Deck(deck_id, deck_title) + + +def add_note(deck, model, prompt, answer, qtext, atext, media_files, tag): + qfile = f"q_{tag}.wav" + afile = f"a_{tag}.wav" + qpath = os.path.join(MEDIA_DIR, qfile) + apath = os.path.join(MEDIA_DIR, afile) + piper_tts(qtext, qpath) + piper_tts(atext, apath) + media_files += [qpath, apath] + deck.add_note(genanki.Note( + model=model, + fields=[prompt, answer, f"[sound:{qfile}]", f"[sound:{afile}]"], + )) + + +def gen_prehs(): + deck_key = "periodic_prehs" + model_id, model = build_model(deck_key) + deck = build_deck(deck_key, "Periodic Table: Symbols & Names (1-36)") + media_files = [] + subset = [e for e in ELEMENTS if e[0] <= 36] + cards = [] + for number, symbol, name, category in subset: + cards.append(("symbol_to_name", number, symbol, name)) + cards.append(("name_to_symbol", number, symbol, name)) + random.seed(50) + random.shuffle(cards) + for kind, number, symbol, name in cards: + if kind == "symbol_to_name": + add_note(deck, model, symbol, name, + f"What element has the symbol {symbol}?", name, + media_files, f"prehs_s2n_{number}") + else: + add_note(deck, model, name, symbol, + f"What is the symbol for {name}?", symbol, + media_files, f"prehs_n2s_{number}") + return deck, media_files, len(cards) + + +def gen_hs(): + deck_key = "periodic_hs" + model_id, model = build_model(deck_key) + deck = build_deck(deck_key, "Periodic Table: Symbols, Names & Numbers (1-118)") + media_files = [] + cards = [] + for number, symbol, name, category in ELEMENTS: + cards.append(("symbol_to_name", number, symbol, name)) + cards.append(("name_to_symbol", number, symbol, name)) + cards.append(("number_to_symbol", number, symbol, name)) + random.seed(51) + random.shuffle(cards) + for kind, number, symbol, name in cards: + if kind == "symbol_to_name": + add_note(deck, model, symbol, name, + f"What element has the symbol {symbol}?", name, + media_files, f"hs_s2n_{number}") + elif kind == "name_to_symbol": + add_note(deck, model, name, symbol, + f"What is the symbol for {name}?", symbol, + media_files, f"hs_n2s_{number}") + else: + add_note(deck, model, f"Element #{number}", symbol, + f"What is the symbol for element number {num2words(number)}?", symbol, + media_files, f"hs_num2s_{number}") + return deck, media_files, len(cards) + + +def gen_category(): + deck_key = "periodic_category" + model_id, model = build_model(deck_key) + deck = build_deck(deck_key, "Periodic Table: Element Categories (multiple choice)") + media_files = [] + subset = [e for e in ELEMENTS if e[3] is not None] + random.seed(52) + shuffled = subset[:] + random.shuffle(shuffled) + + letters = ["A", "B", "C", "D"] + for number, symbol, name, category in shuffled: + distractor_pool = [c for c in ALL_CATEGORIES if c != category] + distractors = random.sample(distractor_pool, 3) + choices = distractors + [category] + random.shuffle(choices) + correct_letter = letters[choices.index(category)] + + prompt_lines = [f"{name} ({symbol})", ""] + for letter, choice in zip(letters, choices): + prompt_lines.append(f"{letter}) {choice}") + prompt = "\n".join(prompt_lines) + + qtext = f"What category is {name}?" + atext = f"{category}" + add_note(deck, model, prompt, correct_letter, qtext, atext, + media_files, f"cat_{number}") + return deck, media_files, len(subset) + + +if args.deck == "prehs": + deck_key = "periodic_prehs" +elif args.deck == "hs": + deck_key = "periodic_hs" +else: + deck_key = "periodic_category" + +MEDIA_DIR = os.path.join(SCRATCH, f"media_{deck_key}_{args.voice}") +os.makedirs(MEDIA_DIR, exist_ok=True) + +GENERATORS = {"prehs": gen_prehs, "hs": gen_hs, "category": gen_category} +deck, media_files, count = GENERATORS[args.deck]() + +package = genanki.Package(deck) +package.media_files = media_files +out_path = os.path.join(SCRATCH, f"{deck_key}_{args.voice}.apkg") +package.write_to_file(out_path) + +size_mb = os.path.getsize(out_path) / (1024 * 1024) +print(f"\nDone: {out_path} ({size_mb:.1f} MB, {count} cards, {len(media_files)} audio clips)") diff --git a/tools/anki-deck-visual.py b/tools/anki-deck-visual.py new file mode 100644 index 0000000..5b40340 --- /dev/null +++ b/tools/anki-deck-visual.py @@ -0,0 +1,408 @@ +#!/usr/bin/env python3 +"""tools/anki-deck-visual.py — Generate image-based Anki decks (.apkg) for +shapes, clocks, and coin-counting, with Anki's built-in type-the-answer +input and Piper (offline, local neural TTS) audio. See +tools/anki-deck-math.py's docstring for one-time setup (venv, genanki + +piper-tts, downloading a voice) — same steps apply here. + +All images are drawn programmatically as SVG (regular-polygon geometry, +clock-hand trigonometry, coin layouts) rather than AI-generated — image +generation (local or cloud) is a poor fit for content that has to be +exactly correct (an exact clock time, an exact side count, an exact coin +total), not just plausible-looking. See this script's own point/angle +generation functions for how each shape's geometry is computed directly +rather than approximated. + +Decks: + shapes regular polygons (3-10 sides, image->name and name->sides) + plus 5 quadrilateral types (image->name: square, rectangle, + rhombus, trapezoid, parallelogram — each one's geometry is + genuinely distinct, not just differently labeled) + clocks analog clock faces, all 144 hour/5-min combinations, + type the time as H:MM (the hour hand moves fractionally + with the minutes, e.g. 6:30 sits halfway between 6 and 7 — + a static hour hand is the most common "looks right but + teaches wrong" bug in generated clock faces) + currency US coins (nickel/dime/quarter — no pennies, since they're + barely used day to day at this point), 1-4 coins per card, + type the total in cents + +Usage (run with the venv from anki-deck-math.py's docstring activated): + python3 anki-deck-visual.py --deck shapes + python3 anki-deck-visual.py --deck clocks + python3 anki-deck-visual.py --deck currency +(add --voice en_US-amy-medium etc.; --model-path if a voice isn't found +automatically; --dry-run-tts to test the deck-building logic without any +voice model at all, using silent placeholder audio) +""" +import argparse +import hashlib +import genanki +import math +import os +import random +import subprocess + +parser = argparse.ArgumentParser() +parser.add_argument("--deck", required=True, choices=["shapes", "clocks", "currency"]) +parser.add_argument("--voice", default="en_US-lessac-medium") +parser.add_argument("--model-path", default=None) +parser.add_argument("--dry-run-tts", action="store_true") +args = parser.parse_args() + +SCRATCH = os.path.dirname(os.path.abspath(__file__)) + +_CANDIDATES = [ + args.model_path, + f"{args.voice}.onnx", + os.path.join(SCRATCH, f"{args.voice}.onnx"), + os.path.expanduser(f"~/{args.voice}.onnx"), + os.path.expanduser(f"~/.local/share/piper/voices/{args.voice}.onnx"), +] +VOICE_MODEL = next((p for p in _CANDIDATES if p and os.path.isfile(p)), None) + +if VOICE_MODEL is None and not args.dry_run_tts: + raise SystemExit( + f"Voice model for '{args.voice}' not found. Checked:\n" + + "\n".join(f" {p}" for p in _CANDIDATES if p) + + f"\n\nFind it with: find / -iname '{args.voice}.onnx' 2>/dev/null" + + "\nThen pass its exact path with --model-path /the/real/path.onnx" + + "\n(or pass --dry-run-tts to test deck-building without any voice at all)" + ) + + +def piper_tts(text: str, out_path: str) -> None: + if args.dry_run_tts: + with open(out_path, "wb") as f: + f.write( + b"RIFF$\x00\x00\x00WAVEfmt \x10\x00\x00\x00\x01\x00\x01\x00" + b"\x22\x56\x00\x00\x44\xac\x00\x00\x02\x00\x10\x00data\x00\x00\x00\x00" + ) + return + subprocess.run( + ["python3", "-m", "piper", "-m", VOICE_MODEL, "-f", out_path], + input=text.encode("utf-8"), + check=True, + capture_output=True, + ) + + +ONES = ["zero", "one", "two", "three", "four", "five", "six", "seven", + "eight", "nine", "ten", "eleven", "twelve", "thirteen", "fourteen", + "fifteen", "sixteen", "seventeen", "eighteen", "nineteen"] +TENS = ["", "", "twenty", "thirty", "forty", "fifty", "sixty", "seventy", + "eighty", "ninety"] + + +def num2words(n): + if n < 20: + return ONES[n] + if n < 100: + t, o = divmod(n, 10) + return TENS[t] + ("-" + ONES[o] if o else "") + h, rem = divmod(n, 100) + return ONES[h] + " hundred" + (" " + num2words(rem) if rem else "") + + +assert num2words(15) == "fifteen" +assert num2words(40) == "forty" + + +def time_words(hour, minute): + """3, 5 -> 'three oh five'; 3, 15 -> 'three fifteen'; 3, 0 -> 'three o'clock'.""" + if minute == 0: + return f"{num2words(hour)} o'clock" + if minute < 10: + return f"{num2words(hour)} oh {num2words(minute)}" + return f"{num2words(hour)} {num2words(minute)}" + + +assert time_words(3, 0) == "three o'clock" +assert time_words(3, 5) == "three oh five" +assert time_words(3, 15) == "three fifteen" +assert time_words(12, 45) == "twelve forty-five" + + +def build_model(deck_key): + voice_hash = int(hashlib.sha256(f"{deck_key}:{args.voice}".encode()).hexdigest(), 16) + model_id = 1_800_000_000 + (voice_hash % 90_000_000) + return model_id, genanki.Model( + model_id, + f"Visual Fact ({deck_key}, {args.voice})", + fields=[{"name": "Image"}, {"name": "Answer"}, {"name": "QSound"}, {"name": "ASound"}], + templates=[{ + "name": "Card", + "qfmt": """ +
+{{type:Answer}} +{{ASound}} +""", + }], + css=""" +.card { font-family: Arial, sans-serif; font-size: 24px; text-align: center; } +.imgwrap { margin: 10px auto; } +.imgwrap img { max-width: 260px; max-height: 260px; } +""", + ) + + +def build_deck(deck_key, deck_title): + voice_hash = int(hashlib.sha256(f"{deck_key}:{args.voice}".encode()).hexdigest(), 16) + deck_id = 2_200_000_000 + (voice_hash % 90_000_000) + return genanki.Deck(deck_id, deck_title) + + +def add_note(deck, model, image_html, answer, qtext, atext, media_files, tag): + qfile = f"q_{tag}.wav" + afile = f"a_{tag}.wav" + qpath = os.path.join(MEDIA_DIR, qfile) + apath = os.path.join(MEDIA_DIR, afile) + piper_tts(qtext, qpath) + piper_tts(atext, apath) + media_files += [qpath, apath] + deck.add_note(genanki.Note( + model=model, + fields=[image_html, answer, f"[sound:{qfile}]", f"[sound:{afile}]"], + )) + + +def add_text_note(deck, model, text, answer, qtext, atext, media_files, tag): + """For directions that don't need an image (e.g. name -> number of sides).""" + add_note(deck, model, f'{h} ')
+
+ body = (
+ f'{label} '
+ )
+ return "".join(parts)
+
+
+def coin_list_words(coin_values):
+ names = [COIN_NAMES[v] for v in coin_values]
+ if len(names) == 1:
+ return f"a {names[0]}"
+ if len(names) == 2:
+ return f"a {names[0]} and a {names[1]}"
+ return ", ".join(f"a {n}" for n in names[:-1]) + f", and a {names[-1]}"
+
+
+# ─── Per-deck generators ─────────────────────────────────────────────────────
+def gen_shapes():
+ deck_key = "shapes"
+ model_id, model = build_model(deck_key)
+ deck = build_deck(deck_key, "Shapes: Polygons & Quadrilaterals")
+ media_files = []
+
+ jobs = []
+ for n in range(3, 11):
+ jobs.append(("polygon_image", n))
+ jobs.append(("polygon_sides", n))
+ for qname in QUADRILATERALS:
+ jobs.append(("quad_image", qname))
+ random.seed(60)
+ random.shuffle(jobs)
+
+ for kind, val in jobs:
+ if kind == "polygon_image":
+ n = val
+ name = POLYGON_NAMES[n]
+ svg_path = save_svg(polygon_svg(regular_polygon_points(n)), f"poly_{n}.svg")
+ media_files.append(svg_path)
+ add_note(deck, model, f'
', name,
+ "What shape is this?", name, media_files, f"shape_img_{n}")
+ elif kind == "polygon_sides":
+ n = val
+ name = POLYGON_NAMES[n]
+ add_text_note(deck, model, name.capitalize(), str(n),
+ f"How many sides does a {name} have?", num2words(n),
+ media_files, f"shape_sides_{n}")
+ else:
+ qname = val
+ svg_path = save_svg(polygon_svg(QUADRILATERALS[qname]), f"quad_{qname}.svg")
+ media_files.append(svg_path)
+ add_note(deck, model, f'
', qname,
+ "What shape is this?", qname, media_files, f"shape_quad_{qname}")
+ return deck, media_files, len(jobs)
+
+
+def gen_clocks():
+ deck_key = "clocks"
+ model_id, model = build_model(deck_key)
+ deck = build_deck(deck_key, "Telling Time: Analog Clocks")
+ media_files = []
+
+ times = [(h, m) for h in range(1, 13) for m in range(0, 60, 5)]
+ random.seed(61)
+ random.shuffle(times)
+
+ # The question prompt ("What time is it?") is identical for every card —
+ # generate it once instead of 144 times.
+ shared_qfile = "q_clock_prompt.wav"
+ piper_tts("What time is it?", os.path.join(MEDIA_DIR, shared_qfile))
+ media_files.append(os.path.join(MEDIA_DIR, shared_qfile))
+
+ for hour, minute in times:
+ svg_path = save_svg(clock_svg(hour, minute), f"clock_{hour}_{minute:02d}.svg")
+ media_files.append(svg_path)
+ answer = f"{hour}:{minute:02d}"
+ afile = f"a_clock_{hour}_{minute:02d}.wav"
+ apath = os.path.join(MEDIA_DIR, afile)
+ piper_tts(time_words(hour, minute), apath)
+ media_files.append(apath)
+ deck.add_note(genanki.Note(
+ model=model,
+ fields=[f'
', answer,
+ f"[sound:{shared_qfile}]", f"[sound:{afile}]"],
+ ))
+ return deck, media_files, len(times)
+
+
+def gen_currency():
+ deck_key = "currency"
+ model_id, model = build_model(deck_key)
+ # Deliberately nickel/dime/quarter only, no pennies — pennies are barely
+ # used day to day at this point, and skipping them keeps every total a
+ # multiple of 5 cents, which is a cleaner first pass at coin counting.
+ deck = build_deck(deck_key, "Counting Coins (nickels, dimes, quarters)")
+ media_files = []
+ denoms = [5, 10, 25]
+
+ combos = set()
+ for count in range(1, 5):
+ def rec(remaining, current):
+ if remaining == 0:
+ combos.add(tuple(sorted(current)))
+ return
+ for d in denoms:
+ if not current or d >= current[-1]:
+ rec(remaining - 1, current + [d])
+ rec(count, [])
+ combos = sorted(combos)
+ random.seed(62)
+ random.shuffle(combos)
+
+ for coin_values in combos:
+ total = sum(coin_values)
+ svg_path = save_svg(coins_svg(list(coin_values)), f"coins_{'_'.join(map(str, coin_values))}.svg")
+ media_files.append(svg_path)
+ qtext = f"How much money is {coin_list_words(list(coin_values))}?"
+ atext = f"{num2words(total)} cents"
+ add_note(deck, model, f'
',
+ str(total), qtext, atext, media_files, f"coins_{'_'.join(map(str, coin_values))}")
+ return deck, media_files, len(combos)
+
+
+if args.deck == "shapes":
+ deck_key = "shapes"
+elif args.deck == "clocks":
+ deck_key = "clocks"
+else:
+ deck_key = "currency"
+
+MEDIA_DIR = os.path.join(SCRATCH, f"media_{deck_key}_{args.voice}")
+os.makedirs(MEDIA_DIR, exist_ok=True)
+
+GENERATORS = {"shapes": gen_shapes, "clocks": gen_clocks, "currency": gen_currency}
+deck, media_files, count = GENERATORS[args.deck]()
+
+package = genanki.Package(deck)
+package.media_files = media_files
+out_path = os.path.join(SCRATCH, f"{deck_key}_{args.voice}.apkg")
+package.write_to_file(out_path)
+
+size_mb = os.path.getsize(out_path) / (1024 * 1024)
+print(f"\nDone: {out_path} ({size_mb:.1f} MB, {count} cards, {len(media_files)} media files)")
+
+{{QSound}}
+{{type:Answer}}
+""",
+ "afmt": """
+{{Top}}
+ {{Bottom}}
+
+
+
+{{Top}}
+ {{Bottom}}
+
++{{type:Answer}} +{{ASound}} +""", + }], + css=""" +.card { font-family: Arial, sans-serif; font-size: 28px; text-align: center; } +.problem { display: inline-block; text-align: right; margin: 20px auto; } +.line1, .line2 { font-size: 48px; padding: 2px 10px; } +.rule { border-top: 3px solid black; margin-top: 4px; width: 100%; } +""", + ) + + +def build_deck(deck_key, deck_title): + voice_hash = int(hashlib.sha256(f"{deck_key}:{args.voice}".encode()).hexdigest(), 16) + deck_id = 2_000_000_000 + (voice_hash % 90_000_000) + return genanki.Deck(deck_id, deck_title) + + +def add_note(deck, model, top, bottom, answer, qtext, atext, media_files, tag): + qfile = f"q_{tag}.wav" + afile = f"a_{tag}.wav" + qpath = os.path.join(MEDIA_DIR, qfile) + apath = os.path.join(MEDIA_DIR, afile) + piper_tts(qtext, qpath) + piper_tts(atext, apath) + media_files += [qpath, apath] + deck.add_note(genanki.Note( + model=model, + fields=[top, bottom, answer, f"[sound:{qfile}]", f"[sound:{afile}]"], + )) + + +# ─── Per-deck generators ───────────────────────────────────────────────────── +def gen_multiplication(): + deck_key = "multiplication" + model_id, model = build_model(deck_key) + deck = build_deck(deck_key, "Multiplication Facts (1-12)") + media_files = [] + pairs = [(a, b) for a in range(1, 13) for b in range(1, 13)] + random.seed(42) + random.shuffle(pairs) + for a, b in pairs: + ans = a * b + add_note(deck, model, str(a), f"× {b}", str(ans), + f"{num2words(a)} times {num2words(b)}", num2words(ans), + media_files, f"mul_{a}_{b}") + return deck, media_files, len(pairs) + + +def gen_division(): + deck_key = "division" + model_id, model = build_model(deck_key) + deck = build_deck(deck_key, "Division Facts (inverse of 1-12 times tables)") + media_files = [] + # Same (a, b) pairs as multiplication: product / a = b. This is the + # direct inverse of every multiplication card in that deck. + pairs = [(a, b) for a in range(1, 13) for b in range(1, 13)] + random.seed(43) + random.shuffle(pairs) + for a, b in pairs: + product = a * b + add_note(deck, model, str(product), f"÷ {a}", str(b), + f"{num2words(product)} divided by {num2words(a)}", num2words(b), + media_files, f"div_{a}_{b}") + return deck, media_files, len(pairs) + + +def gen_addsub(lo, hi): + deck_key = f"addsub_{lo}_{hi}" + model_id, model = build_model(deck_key) + deck = build_deck(deck_key, f"Addition & Subtraction Facts ({lo}-{hi})") + media_files = [] + + add_pairs = [(a, b) for a in range(lo, hi + 1) for b in range(lo, hi + 1)] + random.seed(hash((lo, hi)) & 0xFFFFFFFF) + random.shuffle(add_pairs) + + sub_facts = [] # (minuend, subtrahend, answer) + seen = set() + for a, b in add_pairs: + c = a + b + for minuend, subtrahend, answer in ((c, a, b), (c, b, a)): + key = (minuend, subtrahend) + if key not in seen: + seen.add(key) + sub_facts.append((minuend, subtrahend, answer)) + random.shuffle(sub_facts) + + count = 0 + for a, b in add_pairs: + ans = a + b + add_note(deck, model, str(a), f"+ {b}", str(ans), + f"{num2words(a)} plus {num2words(b)}", num2words(ans), + media_files, f"add_{lo}_{hi}_{a}_{b}") + count += 1 + for minuend, subtrahend, answer in sub_facts: + add_note(deck, model, str(minuend), f"− {subtrahend}", str(answer), + f"{num2words(minuend)} minus {num2words(subtrahend)}", num2words(answer), + media_files, f"sub_{lo}_{hi}_{minuend}_{subtrahend}") + count += 1 + return deck, media_files, count + + +def gen_fractions(): + deck_key = "fractions" + model_id, model = build_model(deck_key) + deck = build_deck(deck_key, "Reducing Fractions to Lowest Terms") + media_files = [] + + facts = [] + for den in range(2, 13): + for num in range(1, den): + g = math.gcd(num, den) + if g > 1: + facts.append((num, den, num // g, den // g)) + random.seed(44) + random.shuffle(facts) + + for num, den, rnum, rden in facts: + answer = f"{rnum}/{rden}" + add_note(deck, model, str(num), f"⁄ {den}", answer, + fraction_words(num, den), fraction_words(rnum, rden), + media_files, f"frac_{num}_{den}") + return deck, media_files, len(facts) + + +def gen_decimals(): + deck_key = "decimals" + model_id, model = build_model(deck_key) + deck = build_deck(deck_key, "Fraction to Decimal Conversion") + media_files = [] + + # Only denominators whose only prime factors are 2 and 5 terminate in a + # finite decimal (1/3 = 0.333... never terminates) — restricting to + # these avoids ever needing to round/repeat. + facts = [] + for den in (2, 4, 5, 8, 10, 20, 25): + for num in range(1, den): + if math.gcd(num, den) != 1: + continue # skip non-lowest-terms fractions (already covered by the fractions deck) + value = num / den + decimal_str = f"{value:.10f}".rstrip("0") + if decimal_str.endswith("."): + decimal_str += "0" + facts.append((num, den, decimal_str)) + random.seed(45) + random.shuffle(facts) + + for num, den, decimal_str in facts: + add_note(deck, model, str(num), f"⁄ {den}", decimal_str, + fraction_words(num, den), decimal_words(decimal_str), + media_files, f"dec_{num}_{den}") + return deck, media_files, len(facts) + + +# ─── Dispatch ───────────────────────────────────────────────────────────────── +if args.deck == "addsub": + deck_key = f"addsub_{args.lo}_{args.hi}" +else: + deck_key = args.deck + +MEDIA_DIR = os.path.join(SCRATCH, f"media_{deck_key}_{args.voice}") +os.makedirs(MEDIA_DIR, exist_ok=True) + +GENERATORS = { + "multiplication": lambda: gen_multiplication(), + "division": lambda: gen_division(), + "addsub": lambda: gen_addsub(args.lo, args.hi), + "fractions": lambda: gen_fractions(), + "decimals": lambda: gen_decimals(), +} + +deck, media_files, count = GENERATORS[args.deck]() +if count == 0: + raise SystemExit(f"No cards generated for --deck {args.deck} — check the range/args.") + +package = genanki.Package(deck) +package.media_files = media_files +out_path = os.path.join(SCRATCH, f"{deck_key}_{args.voice}.apkg") +package.write_to_file(out_path) + +size_mb = os.path.getsize(out_path) / (1024 * 1024) +print(f"\nDone: {out_path} ({size_mb:.1f} MB, {count} cards, {len(media_files)} audio clips)") diff --git a/tools/anki-deck-periodic.py b/tools/anki-deck-periodic.py new file mode 100644 index 0000000..784c6cb --- /dev/null +++ b/tools/anki-deck-periodic.py @@ -0,0 +1,385 @@ +#!/usr/bin/env python3 +"""tools/anki-deck-periodic.py — Generate periodic table Anki decks (.apkg) +with Anki's built-in type-the-answer input and Piper (offline, local +neural TTS) audio on both sides. See tools/anki-deck-math.py's docstring +for one-time setup (venv, genanki + piper-tts, downloading a voice) — same +steps apply here, this is a standalone, self-contained script otherwise. + +Decks: + prehs symbol<->name, elements 1-36 (H through Kr) + hs symbol<->name plus number->symbol, all 118 elements + category element category as multiple choice (A/B/C/D shown as + plain text options — not a clickable UI, since that needs + a desktop-only Anki add-on and would break on + AnkiDroid/AnkiMobile), type the letter — only elements + with a confirmed category (excludes 8 very recent + superheavy elements whose category is still officially + unconfirmed) + +Element data: Bowserinator/Periodic-Table-JSON (a widely used, actively +maintained public dataset), fetched and spot-checked against known facts +before being embedded below — not typed from memory. + +Usage (run with the venv from anki-deck-math.py's docstring activated): + python3 anki-deck-periodic.py --deck prehs + python3 anki-deck-periodic.py --deck hs + python3 anki-deck-periodic.py --deck category +(add --voice en_US-amy-medium etc.; --model-path if a voice isn't found +automatically; --dry-run-tts to test the deck-building logic without any +voice model at all, using silent placeholder audio) +""" +import argparse +import hashlib +import genanki +import os +import random +import subprocess + +parser = argparse.ArgumentParser() +parser.add_argument("--deck", required=True, choices=["prehs", "hs", "category"]) +parser.add_argument("--voice", default="en_US-lessac-medium") +parser.add_argument("--model-path", default=None) +parser.add_argument("--dry-run-tts", action="store_true") +args = parser.parse_args() + +SCRATCH = os.path.dirname(os.path.abspath(__file__)) + +_CANDIDATES = [ + args.model_path, + f"{args.voice}.onnx", + os.path.join(SCRATCH, f"{args.voice}.onnx"), + os.path.expanduser(f"~/{args.voice}.onnx"), + os.path.expanduser(f"~/.local/share/piper/voices/{args.voice}.onnx"), +] +VOICE_MODEL = next((p for p in _CANDIDATES if p and os.path.isfile(p)), None) + +if VOICE_MODEL is None and not args.dry_run_tts: + raise SystemExit( + f"Voice model for '{args.voice}' not found. Checked:\n" + + "\n".join(f" {p}" for p in _CANDIDATES if p) + + f"\n\nFind it with: find / -iname '{args.voice}.onnx' 2>/dev/null" + + "\nThen pass its exact path with --model-path /the/real/path.onnx" + + "\n(or pass --dry-run-tts to test deck-building without any voice at all)" + ) + + +def piper_tts(text: str, out_path: str) -> None: + if args.dry_run_tts: + with open(out_path, "wb") as f: + f.write( + b"RIFF$\x00\x00\x00WAVEfmt \x10\x00\x00\x00\x01\x00\x01\x00" + b"\x22\x56\x00\x00\x44\xac\x00\x00\x02\x00\x10\x00data\x00\x00\x00\x00" + ) + return + subprocess.run( + ["python3", "-m", "piper", "-m", VOICE_MODEL, "-f", out_path], + input=text.encode("utf-8"), + check=True, + capture_output=True, + ) + + +ONES = ["zero", "one", "two", "three", "four", "five", "six", "seven", + "eight", "nine", "ten", "eleven", "twelve", "thirteen", "fourteen", + "fifteen", "sixteen", "seventeen", "eighteen", "nineteen"] +TENS = ["", "", "twenty", "thirty", "forty", "fifty", "sixty", "seventy", + "eighty", "ninety"] + + +def num2words(n): + if n < 20: + return ONES[n] + if n < 100: + t, o = divmod(n, 10) + return TENS[t] + ("-" + ONES[o] if o else "") + h, rem = divmod(n, 100) + return ONES[h] + " hundred" + (" " + num2words(rem) if rem else "") + + +assert num2words(1) == "one" +assert num2words(26) == "twenty-six" +assert num2words(118) == "one hundred eighteen" + +# ─── Element data: (atomic_number, symbol, name, category-or-None) ───────── +# category is None for the 8 most recently synthesized superheavy elements +# whose chemical category is still officially unconfirmed (excluded from +# the category deck below, still included in prehs/hs symbol/name/number). +ELEMENTS = [ + (1, 'H', 'Hydrogen', 'diatomic nonmetal'), + (2, 'He', 'Helium', 'noble gas'), + (3, 'Li', 'Lithium', 'alkali metal'), + (4, 'Be', 'Beryllium', 'alkaline earth metal'), + (5, 'B', 'Boron', 'metalloid'), + (6, 'C', 'Carbon', 'polyatomic nonmetal'), + (7, 'N', 'Nitrogen', 'diatomic nonmetal'), + (8, 'O', 'Oxygen', 'diatomic nonmetal'), + (9, 'F', 'Fluorine', 'diatomic nonmetal'), + (10, 'Ne', 'Neon', 'noble gas'), + (11, 'Na', 'Sodium', 'alkali metal'), + (12, 'Mg', 'Magnesium', 'alkaline earth metal'), + (13, 'Al', 'Aluminium', 'post-transition metal'), + (14, 'Si', 'Silicon', 'metalloid'), + (15, 'P', 'Phosphorus', 'polyatomic nonmetal'), + (16, 'S', 'Sulfur', 'polyatomic nonmetal'), + (17, 'Cl', 'Chlorine', 'diatomic nonmetal'), + (18, 'Ar', 'Argon', 'noble gas'), + (19, 'K', 'Potassium', 'alkali metal'), + (20, 'Ca', 'Calcium', 'alkaline earth metal'), + (21, 'Sc', 'Scandium', 'transition metal'), + (22, 'Ti', 'Titanium', 'transition metal'), + (23, 'V', 'Vanadium', 'transition metal'), + (24, 'Cr', 'Chromium', 'transition metal'), + (25, 'Mn', 'Manganese', 'transition metal'), + (26, 'Fe', 'Iron', 'transition metal'), + (27, 'Co', 'Cobalt', 'transition metal'), + (28, 'Ni', 'Nickel', 'transition metal'), + (29, 'Cu', 'Copper', 'transition metal'), + (30, 'Zn', 'Zinc', 'transition metal'), + (31, 'Ga', 'Gallium', 'post-transition metal'), + (32, 'Ge', 'Germanium', 'metalloid'), + (33, 'As', 'Arsenic', 'metalloid'), + (34, 'Se', 'Selenium', 'polyatomic nonmetal'), + (35, 'Br', 'Bromine', 'diatomic nonmetal'), + (36, 'Kr', 'Krypton', 'noble gas'), + (37, 'Rb', 'Rubidium', 'alkali metal'), + (38, 'Sr', 'Strontium', 'alkaline earth metal'), + (39, 'Y', 'Yttrium', 'transition metal'), + (40, 'Zr', 'Zirconium', 'transition metal'), + (41, 'Nb', 'Niobium', 'transition metal'), + (42, 'Mo', 'Molybdenum', 'transition metal'), + (43, 'Tc', 'Technetium', 'transition metal'), + (44, 'Ru', 'Ruthenium', 'transition metal'), + (45, 'Rh', 'Rhodium', 'transition metal'), + (46, 'Pd', 'Palladium', 'transition metal'), + (47, 'Ag', 'Silver', 'transition metal'), + (48, 'Cd', 'Cadmium', 'transition metal'), + (49, 'In', 'Indium', 'post-transition metal'), + (50, 'Sn', 'Tin', 'post-transition metal'), + (51, 'Sb', 'Antimony', 'metalloid'), + (52, 'Te', 'Tellurium', 'metalloid'), + (53, 'I', 'Iodine', 'diatomic nonmetal'), + (54, 'Xe', 'Xenon', 'noble gas'), + (55, 'Cs', 'Cesium', 'alkali metal'), + (56, 'Ba', 'Barium', 'alkaline earth metal'), + (57, 'La', 'Lanthanum', 'lanthanide'), + (58, 'Ce', 'Cerium', 'lanthanide'), + (59, 'Pr', 'Praseodymium', 'lanthanide'), + (60, 'Nd', 'Neodymium', 'lanthanide'), + (61, 'Pm', 'Promethium', 'lanthanide'), + (62, 'Sm', 'Samarium', 'lanthanide'), + (63, 'Eu', 'Europium', 'lanthanide'), + (64, 'Gd', 'Gadolinium', 'lanthanide'), + (65, 'Tb', 'Terbium', 'lanthanide'), + (66, 'Dy', 'Dysprosium', 'lanthanide'), + (67, 'Ho', 'Holmium', 'lanthanide'), + (68, 'Er', 'Erbium', 'lanthanide'), + (69, 'Tm', 'Thulium', 'lanthanide'), + (70, 'Yb', 'Ytterbium', 'lanthanide'), + (71, 'Lu', 'Lutetium', 'lanthanide'), + (72, 'Hf', 'Hafnium', 'transition metal'), + (73, 'Ta', 'Tantalum', 'transition metal'), + (74, 'W', 'Tungsten', 'transition metal'), + (75, 'Re', 'Rhenium', 'transition metal'), + (76, 'Os', 'Osmium', 'transition metal'), + (77, 'Ir', 'Iridium', 'transition metal'), + (78, 'Pt', 'Platinum', 'transition metal'), + (79, 'Au', 'Gold', 'transition metal'), + (80, 'Hg', 'Mercury', 'transition metal'), + (81, 'Tl', 'Thallium', 'post-transition metal'), + (82, 'Pb', 'Lead', 'post-transition metal'), + (83, 'Bi', 'Bismuth', 'post-transition metal'), + (84, 'Po', 'Polonium', 'post-transition metal'), + (85, 'At', 'Astatine', 'diatomic nonmetal'), + (86, 'Rn', 'Radon', 'noble gas'), + (87, 'Fr', 'Francium', 'alkali metal'), + (88, 'Ra', 'Radium', 'alkaline earth metal'), + (89, 'Ac', 'Actinium', 'actinide'), + (90, 'Th', 'Thorium', 'actinide'), + (91, 'Pa', 'Protactinium', 'actinide'), + (92, 'U', 'Uranium', 'actinide'), + (93, 'Np', 'Neptunium', 'actinide'), + (94, 'Pu', 'Plutonium', 'actinide'), + (95, 'Am', 'Americium', 'actinide'), + (96, 'Cm', 'Curium', 'actinide'), + (97, 'Bk', 'Berkelium', 'actinide'), + (98, 'Cf', 'Californium', 'actinide'), + (99, 'Es', 'Einsteinium', 'actinide'), + (100, 'Fm', 'Fermium', 'actinide'), + (101, 'Md', 'Mendelevium', 'actinide'), + (102, 'No', 'Nobelium', 'actinide'), + (103, 'Lr', 'Lawrencium', 'actinide'), + (104, 'Rf', 'Rutherfordium', 'transition metal'), + (105, 'Db', 'Dubnium', 'transition metal'), + (106, 'Sg', 'Seaborgium', 'transition metal'), + (107, 'Bh', 'Bohrium', 'transition metal'), + (108, 'Hs', 'Hassium', 'transition metal'), + (109, 'Mt', 'Meitnerium', None), + (110, 'Ds', 'Darmstadtium', None), + (111, 'Rg', 'Roentgenium', None), + (112, 'Cn', 'Copernicium', None), + (113, 'Nh', 'Nihonium', 'post-transition metal'), + (114, 'Fl', 'Flerovium', 'post-transition metal'), + (115, 'Mc', 'Moscovium', None), + (116, 'Lv', 'Livermorium', None), + (117, 'Ts', 'Tennessine', None), + (118, 'Og', 'Oganesson', None), +] +assert len(ELEMENTS) == 118 +assert [e[0] for e in ELEMENTS] == list(range(1, 119)) +assert ELEMENTS[0] == (1, 'H', 'Hydrogen', 'diatomic nonmetal') +assert ELEMENTS[25] == (26, 'Fe', 'Iron', 'transition metal') +assert ELEMENTS[-1] == (118, 'Og', 'Oganesson', None) + +ALL_CATEGORIES = sorted({e[3] for e in ELEMENTS if e[3] is not None}) + + +def build_model(deck_key): + voice_hash = int(hashlib.sha256(f"{deck_key}:{args.voice}".encode()).hexdigest(), 16) + model_id = 1_700_000_000 + (voice_hash % 90_000_000) + return model_id, genanki.Model( + model_id, + f"Periodic Table ({deck_key}, {args.voice})", + fields=[{"name": "Prompt"}, {"name": "Answer"}, {"name": "QSound"}, {"name": "ASound"}], + templates=[{ + "name": "Card", + "qfmt": """ +
{{Prompt}}
+{{QSound}}
+{{type:Answer}}
+""",
+ "afmt": """
+{{Prompt}}
++{{type:Answer}} +{{ASound}} +""", + }], + css=""" +.card { font-family: Arial, sans-serif; font-size: 26px; text-align: center; } +.prompt { font-size: 40px; margin: 20px auto; white-space: pre-line; } +""", + ) + + +def build_deck(deck_key, deck_title): + voice_hash = int(hashlib.sha256(f"{deck_key}:{args.voice}".encode()).hexdigest(), 16) + deck_id = 2_100_000_000 + (voice_hash % 90_000_000) + return genanki.Deck(deck_id, deck_title) + + +def add_note(deck, model, prompt, answer, qtext, atext, media_files, tag): + qfile = f"q_{tag}.wav" + afile = f"a_{tag}.wav" + qpath = os.path.join(MEDIA_DIR, qfile) + apath = os.path.join(MEDIA_DIR, afile) + piper_tts(qtext, qpath) + piper_tts(atext, apath) + media_files += [qpath, apath] + deck.add_note(genanki.Note( + model=model, + fields=[prompt, answer, f"[sound:{qfile}]", f"[sound:{afile}]"], + )) + + +def gen_prehs(): + deck_key = "periodic_prehs" + model_id, model = build_model(deck_key) + deck = build_deck(deck_key, "Periodic Table: Symbols & Names (1-36)") + media_files = [] + subset = [e for e in ELEMENTS if e[0] <= 36] + cards = [] + for number, symbol, name, category in subset: + cards.append(("symbol_to_name", number, symbol, name)) + cards.append(("name_to_symbol", number, symbol, name)) + random.seed(50) + random.shuffle(cards) + for kind, number, symbol, name in cards: + if kind == "symbol_to_name": + add_note(deck, model, symbol, name, + f"What element has the symbol {symbol}?", name, + media_files, f"prehs_s2n_{number}") + else: + add_note(deck, model, name, symbol, + f"What is the symbol for {name}?", symbol, + media_files, f"prehs_n2s_{number}") + return deck, media_files, len(cards) + + +def gen_hs(): + deck_key = "periodic_hs" + model_id, model = build_model(deck_key) + deck = build_deck(deck_key, "Periodic Table: Symbols, Names & Numbers (1-118)") + media_files = [] + cards = [] + for number, symbol, name, category in ELEMENTS: + cards.append(("symbol_to_name", number, symbol, name)) + cards.append(("name_to_symbol", number, symbol, name)) + cards.append(("number_to_symbol", number, symbol, name)) + random.seed(51) + random.shuffle(cards) + for kind, number, symbol, name in cards: + if kind == "symbol_to_name": + add_note(deck, model, symbol, name, + f"What element has the symbol {symbol}?", name, + media_files, f"hs_s2n_{number}") + elif kind == "name_to_symbol": + add_note(deck, model, name, symbol, + f"What is the symbol for {name}?", symbol, + media_files, f"hs_n2s_{number}") + else: + add_note(deck, model, f"Element #{number}", symbol, + f"What is the symbol for element number {num2words(number)}?", symbol, + media_files, f"hs_num2s_{number}") + return deck, media_files, len(cards) + + +def gen_category(): + deck_key = "periodic_category" + model_id, model = build_model(deck_key) + deck = build_deck(deck_key, "Periodic Table: Element Categories (multiple choice)") + media_files = [] + subset = [e for e in ELEMENTS if e[3] is not None] + random.seed(52) + shuffled = subset[:] + random.shuffle(shuffled) + + letters = ["A", "B", "C", "D"] + for number, symbol, name, category in shuffled: + distractor_pool = [c for c in ALL_CATEGORIES if c != category] + distractors = random.sample(distractor_pool, 3) + choices = distractors + [category] + random.shuffle(choices) + correct_letter = letters[choices.index(category)] + + prompt_lines = [f"{name} ({symbol})", ""] + for letter, choice in zip(letters, choices): + prompt_lines.append(f"{letter}) {choice}") + prompt = "\n".join(prompt_lines) + + qtext = f"What category is {name}?" + atext = f"{category}" + add_note(deck, model, prompt, correct_letter, qtext, atext, + media_files, f"cat_{number}") + return deck, media_files, len(subset) + + +if args.deck == "prehs": + deck_key = "periodic_prehs" +elif args.deck == "hs": + deck_key = "periodic_hs" +else: + deck_key = "periodic_category" + +MEDIA_DIR = os.path.join(SCRATCH, f"media_{deck_key}_{args.voice}") +os.makedirs(MEDIA_DIR, exist_ok=True) + +GENERATORS = {"prehs": gen_prehs, "hs": gen_hs, "category": gen_category} +deck, media_files, count = GENERATORS[args.deck]() + +package = genanki.Package(deck) +package.media_files = media_files +out_path = os.path.join(SCRATCH, f"{deck_key}_{args.voice}.apkg") +package.write_to_file(out_path) + +size_mb = os.path.getsize(out_path) / (1024 * 1024) +print(f"\nDone: {out_path} ({size_mb:.1f} MB, {count} cards, {len(media_files)} audio clips)") diff --git a/tools/anki-deck-visual.py b/tools/anki-deck-visual.py new file mode 100644 index 0000000..5b40340 --- /dev/null +++ b/tools/anki-deck-visual.py @@ -0,0 +1,408 @@ +#!/usr/bin/env python3 +"""tools/anki-deck-visual.py — Generate image-based Anki decks (.apkg) for +shapes, clocks, and coin-counting, with Anki's built-in type-the-answer +input and Piper (offline, local neural TTS) audio. See +tools/anki-deck-math.py's docstring for one-time setup (venv, genanki + +piper-tts, downloading a voice) — same steps apply here. + +All images are drawn programmatically as SVG (regular-polygon geometry, +clock-hand trigonometry, coin layouts) rather than AI-generated — image +generation (local or cloud) is a poor fit for content that has to be +exactly correct (an exact clock time, an exact side count, an exact coin +total), not just plausible-looking. See this script's own point/angle +generation functions for how each shape's geometry is computed directly +rather than approximated. + +Decks: + shapes regular polygons (3-10 sides, image->name and name->sides) + plus 5 quadrilateral types (image->name: square, rectangle, + rhombus, trapezoid, parallelogram — each one's geometry is + genuinely distinct, not just differently labeled) + clocks analog clock faces, all 144 hour/5-min combinations, + type the time as H:MM (the hour hand moves fractionally + with the minutes, e.g. 6:30 sits halfway between 6 and 7 — + a static hour hand is the most common "looks right but + teaches wrong" bug in generated clock faces) + currency US coins (nickel/dime/quarter — no pennies, since they're + barely used day to day at this point), 1-4 coins per card, + type the total in cents + +Usage (run with the venv from anki-deck-math.py's docstring activated): + python3 anki-deck-visual.py --deck shapes + python3 anki-deck-visual.py --deck clocks + python3 anki-deck-visual.py --deck currency +(add --voice en_US-amy-medium etc.; --model-path if a voice isn't found +automatically; --dry-run-tts to test the deck-building logic without any +voice model at all, using silent placeholder audio) +""" +import argparse +import hashlib +import genanki +import math +import os +import random +import subprocess + +parser = argparse.ArgumentParser() +parser.add_argument("--deck", required=True, choices=["shapes", "clocks", "currency"]) +parser.add_argument("--voice", default="en_US-lessac-medium") +parser.add_argument("--model-path", default=None) +parser.add_argument("--dry-run-tts", action="store_true") +args = parser.parse_args() + +SCRATCH = os.path.dirname(os.path.abspath(__file__)) + +_CANDIDATES = [ + args.model_path, + f"{args.voice}.onnx", + os.path.join(SCRATCH, f"{args.voice}.onnx"), + os.path.expanduser(f"~/{args.voice}.onnx"), + os.path.expanduser(f"~/.local/share/piper/voices/{args.voice}.onnx"), +] +VOICE_MODEL = next((p for p in _CANDIDATES if p and os.path.isfile(p)), None) + +if VOICE_MODEL is None and not args.dry_run_tts: + raise SystemExit( + f"Voice model for '{args.voice}' not found. Checked:\n" + + "\n".join(f" {p}" for p in _CANDIDATES if p) + + f"\n\nFind it with: find / -iname '{args.voice}.onnx' 2>/dev/null" + + "\nThen pass its exact path with --model-path /the/real/path.onnx" + + "\n(or pass --dry-run-tts to test deck-building without any voice at all)" + ) + + +def piper_tts(text: str, out_path: str) -> None: + if args.dry_run_tts: + with open(out_path, "wb") as f: + f.write( + b"RIFF$\x00\x00\x00WAVEfmt \x10\x00\x00\x00\x01\x00\x01\x00" + b"\x22\x56\x00\x00\x44\xac\x00\x00\x02\x00\x10\x00data\x00\x00\x00\x00" + ) + return + subprocess.run( + ["python3", "-m", "piper", "-m", VOICE_MODEL, "-f", out_path], + input=text.encode("utf-8"), + check=True, + capture_output=True, + ) + + +ONES = ["zero", "one", "two", "three", "four", "five", "six", "seven", + "eight", "nine", "ten", "eleven", "twelve", "thirteen", "fourteen", + "fifteen", "sixteen", "seventeen", "eighteen", "nineteen"] +TENS = ["", "", "twenty", "thirty", "forty", "fifty", "sixty", "seventy", + "eighty", "ninety"] + + +def num2words(n): + if n < 20: + return ONES[n] + if n < 100: + t, o = divmod(n, 10) + return TENS[t] + ("-" + ONES[o] if o else "") + h, rem = divmod(n, 100) + return ONES[h] + " hundred" + (" " + num2words(rem) if rem else "") + + +assert num2words(15) == "fifteen" +assert num2words(40) == "forty" + + +def time_words(hour, minute): + """3, 5 -> 'three oh five'; 3, 15 -> 'three fifteen'; 3, 0 -> 'three o'clock'.""" + if minute == 0: + return f"{num2words(hour)} o'clock" + if minute < 10: + return f"{num2words(hour)} oh {num2words(minute)}" + return f"{num2words(hour)} {num2words(minute)}" + + +assert time_words(3, 0) == "three o'clock" +assert time_words(3, 5) == "three oh five" +assert time_words(3, 15) == "three fifteen" +assert time_words(12, 45) == "twelve forty-five" + + +def build_model(deck_key): + voice_hash = int(hashlib.sha256(f"{deck_key}:{args.voice}".encode()).hexdigest(), 16) + model_id = 1_800_000_000 + (voice_hash % 90_000_000) + return model_id, genanki.Model( + model_id, + f"Visual Fact ({deck_key}, {args.voice})", + fields=[{"name": "Image"}, {"name": "Answer"}, {"name": "QSound"}, {"name": "ASound"}], + templates=[{ + "name": "Card", + "qfmt": """ +
{{Image}}
+{{QSound}}
+{{type:Answer}}
+""",
+ "afmt": """
+{{Image}}
++{{type:Answer}} +{{ASound}} +""", + }], + css=""" +.card { font-family: Arial, sans-serif; font-size: 24px; text-align: center; } +.imgwrap { margin: 10px auto; } +.imgwrap img { max-width: 260px; max-height: 260px; } +""", + ) + + +def build_deck(deck_key, deck_title): + voice_hash = int(hashlib.sha256(f"{deck_key}:{args.voice}".encode()).hexdigest(), 16) + deck_id = 2_200_000_000 + (voice_hash % 90_000_000) + return genanki.Deck(deck_id, deck_title) + + +def add_note(deck, model, image_html, answer, qtext, atext, media_files, tag): + qfile = f"q_{tag}.wav" + afile = f"a_{tag}.wav" + qpath = os.path.join(MEDIA_DIR, qfile) + apath = os.path.join(MEDIA_DIR, afile) + piper_tts(qtext, qpath) + piper_tts(atext, apath) + media_files += [qpath, apath] + deck.add_note(genanki.Note( + model=model, + fields=[image_html, answer, f"[sound:{qfile}]", f"[sound:{afile}]"], + )) + + +def add_text_note(deck, model, text, answer, qtext, atext, media_files, tag): + """For directions that don't need an image (e.g. name -> number of sides).""" + add_note(deck, model, f'
{text}
', answer,
+ qtext, atext, media_files, tag)
+
+
+# ─── SVG generation ───────────────────────────────────────────────────────────
+def save_svg(svg_body, filename, viewbox="0 0 200 200"):
+ path = os.path.join(MEDIA_DIR, filename)
+ with open(path, "w") as f:
+ f.write(
+ f''
+ )
+ return path
+
+
+def regular_polygon_points(n_sides, cx=100, cy=100, r=80):
+ points = []
+ # Start pointing up (-90deg) so shapes sit "upright" rather than vertex-right.
+ start_angle = -90
+ for i in range(n_sides):
+ angle_deg = start_angle + i * (360 / n_sides)
+ angle_rad = math.radians(angle_deg)
+ x = cx + r * math.cos(angle_rad)
+ y = cy + r * math.sin(angle_rad)
+ points.append((round(x, 1), round(y, 1)))
+ return points
+
+
+def polygon_svg(points):
+ pts_str = " ".join(f"{x},{y}" for x, y in points)
+ return f'', name,
+ "What shape is this?", name, media_files, f"shape_img_{n}")
+ elif kind == "polygon_sides":
+ n = val
+ name = POLYGON_NAMES[n]
+ add_text_note(deck, model, name.capitalize(), str(n),
+ f"How many sides does a {name} have?", num2words(n),
+ media_files, f"shape_sides_{n}")
+ else:
+ qname = val
+ svg_path = save_svg(polygon_svg(QUADRILATERALS[qname]), f"quad_{qname}.svg")
+ media_files.append(svg_path)
+ add_note(deck, model, f'', qname,
+ "What shape is this?", qname, media_files, f"shape_quad_{qname}")
+ return deck, media_files, len(jobs)
+
+
+def gen_clocks():
+ deck_key = "clocks"
+ model_id, model = build_model(deck_key)
+ deck = build_deck(deck_key, "Telling Time: Analog Clocks")
+ media_files = []
+
+ times = [(h, m) for h in range(1, 13) for m in range(0, 60, 5)]
+ random.seed(61)
+ random.shuffle(times)
+
+ # The question prompt ("What time is it?") is identical for every card —
+ # generate it once instead of 144 times.
+ shared_qfile = "q_clock_prompt.wav"
+ piper_tts("What time is it?", os.path.join(MEDIA_DIR, shared_qfile))
+ media_files.append(os.path.join(MEDIA_DIR, shared_qfile))
+
+ for hour, minute in times:
+ svg_path = save_svg(clock_svg(hour, minute), f"clock_{hour}_{minute:02d}.svg")
+ media_files.append(svg_path)
+ answer = f"{hour}:{minute:02d}"
+ afile = f"a_clock_{hour}_{minute:02d}.wav"
+ apath = os.path.join(MEDIA_DIR, afile)
+ piper_tts(time_words(hour, minute), apath)
+ media_files.append(apath)
+ deck.add_note(genanki.Note(
+ model=model,
+ fields=[f'', answer,
+ f"[sound:{shared_qfile}]", f"[sound:{afile}]"],
+ ))
+ return deck, media_files, len(times)
+
+
+def gen_currency():
+ deck_key = "currency"
+ model_id, model = build_model(deck_key)
+ # Deliberately nickel/dime/quarter only, no pennies — pennies are barely
+ # used day to day at this point, and skipping them keeps every total a
+ # multiple of 5 cents, which is a cleaner first pass at coin counting.
+ deck = build_deck(deck_key, "Counting Coins (nickels, dimes, quarters)")
+ media_files = []
+ denoms = [5, 10, 25]
+
+ combos = set()
+ for count in range(1, 5):
+ def rec(remaining, current):
+ if remaining == 0:
+ combos.add(tuple(sorted(current)))
+ return
+ for d in denoms:
+ if not current or d >= current[-1]:
+ rec(remaining - 1, current + [d])
+ rec(count, [])
+ combos = sorted(combos)
+ random.seed(62)
+ random.shuffle(combos)
+
+ for coin_values in combos:
+ total = sum(coin_values)
+ svg_path = save_svg(coins_svg(list(coin_values)), f"coins_{'_'.join(map(str, coin_values))}.svg")
+ media_files.append(svg_path)
+ qtext = f"How much money is {coin_list_words(list(coin_values))}?"
+ atext = f"{num2words(total)} cents"
+ add_note(deck, model, f'