HERTZKIT SESSIONS 1.1 — FORMAT AND INTEGRATION Formats 1 and 2 · Reader client 1.0 Developer documentation. For everyday use, see /en/help/#help-sessions. The executable demonstration is at /en/sessions/integration/. The reader opens and plays session context; it does not record audio or modify accounts. The file is portable data, not an authorship certificate or an authoritative grade. FORMAT 1 Extension: .hksession. UTF-8 JSON data, not executable code. Maximum 24 MiB. Root: format="hertzkit-session", version=1, id, activityId, createdAt, updatedAt, language, title, goal, author, source, bpm, a4, instrument, notes, reference, takes, feedback. - id: working-copy UUID; activityId: originating activity UUID. Opening an external file creates a working-copy id so separate replies do not overwrite each other. - notes: 1–64 monophonic notes; midi 36–84; start/duration in quarter-note beats; up to 32 beats and 20 seconds at 40–240 BPM. A4: 400–480 Hz. - reference: rendered, reviewed notes using the existing recorded CC0 bank, encoded as mono 16-bit PCM WAV. The complete source file or bank is not bundled. - audio asset: codec="wav-pcm16-mono", rate, frames, sha256, data (base64). WAV is a canonical 44-byte RIFF header plus mono PCM16. 8–96 kHz, at most 20.5 s including the reference release tail. SHA-256 covers all WAV bytes. - takes: up to 4, each id, createdAt, alias, range{from,to}, input, audio, note. input{key,rate,gain,source,latencyMs}: key is an opaque per-visit configuration token, never the microphone deviceId. Imported takes are marked source="file". - feedback: up to 30; id, createdAt, author, takeId (null for full reference), seconds relative to the selected audio, body (up to 1000 characters). - source: original-example, user-audio, user-midi or user-notes. A source label is a declaration, not verified authorship. All names/codes are also self-declared. Unknown fields, invalid versions, orphan feedback, duplicate ids, malformed WAVs, non-matching hashes and out-of-range data are rejected before replacing work. No encryption, signature, trusted timestamp or proof of prior non-disclosure. Measurements are recomputed when requested using the existing rehearsal engine; the file carries the audio/settings needed, not an authoritative saved grade. Quantitative comparisons require matching recording settings and phrase, the user's explicit same-conditions confirmation and complete usable pitch readings. LOCAL STORAGE Copies are kept in this browser only. Explicit saves only; up to 10 copies and 100 MiB. No account upload, automatic synchronization or school roster. A browser-storage failure keeps the in-memory session; export remains available. Deleting a browser copy does not delete downloaded files or another site's data. READER CLIENT 1.0 Scripts: /assets/js/sessions/session-client.js Reader: /sesiones/reproductor/ or /en/sessions/player/ Constructor: new HKSessionsReaderClient(iframe, {timeout:15000}) Methods, returning promises: ready() load(file) File/Blob, up to 24 MiB play("reference") or play(takeId) pause() seek(seconds) relative to the current audio, 0–20.5 s destroy() removes listeners and rejects pending operations The published component is same-origin only. It does not grant a microphone, open account access, fetch remote media URLs or accept arbitrary HTML. Use on another website requires a separately authorised deployment. The HertzKit-hosted reader does not accept cross-origin embedding. Browser autoplay rules may require a first playback gesture inside the reader. Example (in a self-hosted same-origin page with the matching licensed assets): const reader = new HKSessionsReaderClient(document.querySelector('iframe')); await reader.load(fileInput.files[0]); await reader.play('reference'); await reader.pause(); await reader.seek(1.5); reader.destroy(); POSTMESSAGE TRANSPORT Only event.origin === location.origin AND event.source === expected frame/parent. Use that exact origin in postMessage; never "*". Each request has requestId (max 64 chars). Commands: hertzkit.sessions.ping hertzkit.sessions.load {file} hertzkit.sessions.play {takeId:"reference" | takeId} hertzkit.sessions.pause hertzkit.sessions.seek {seconds} Replies: ready{version:1}, loaded{takes,feedback}, playing, paused, position{seconds}, error{code}, all with prefix hertzkit.sessions. Files are structured-cloned between same-origin windows, not uploaded. The demo reports counts only and does not upload audio, names or observations. PROJECT HANDOFF The explicit Projects button opens preparation in a new tab and offers copying only title, goal and BPM. A temporary same-origin browser channel has a 30-second maximum lifetime. No localStorage and no content in the URL. No notes, tasks, recordings or account data are transferred. The user applies the offered fields explicitly. The original project stays open and is not silently saved. RIGHTS AND COMPATIBILITY Original HertzKit code retains its rights; this technical documentation does not automatically grant a commercial redistribution licence for the complete site. Existing third-party and CC0 recorded-instrument notices remain applicable. The example files are original exercises. Users remain responsible for permission to use and share their recordings. This format is not a DAW exchange standard. Microphone recording needs HTTPS/localhost, Web Audio and AudioWorklet support. File import/playback and local saving depend on browser capabilities and quota. Offline use requires a previously prepared and tested HertzKit offline package. CONTINUITY EXTENSION — FORMAT 2 Current readers accept format 1 and format 2. The postMessage protocol remains version 1; ready also advertises fileVersions:[1,2]. loaded includes rounds. Format 1 files are not automatically rewritten. Organising rounds upgrades the working copy to version 2. Earlier readers should reject version 2, not silently discard it. The compatible-copy export strips journey and writes version 1; keep the version 2 original to preserve goals and round context. Version 2 has the same root fields and limits, plus required journey: {activeRound, rounds, roles:{baseline, final, retest}} Each role is a distinct existing take id or null. rounds has 1–12 entries: {id, createdAt, label, goal, conditions, takeIds, nextStep, focus} label is 1–80 characters; goal 1–1000; conditions 0–500; nextStep 0–1000. focus is null or {from,to}, zero-based note indices into the shared reference. createdAt uses canonical ISO UTC, declared by the device, not a trusted timestamp. All takes belong to exactly one round; every takeId and activeRound must exist. No audio is stored inside rounds. All rounds share the original reference and the existing total limit of four takes, 30 comments and 24 MiB per file. Removing/exporting a subset of takes prunes round memberships and role links; goals and next steps remain. Nothing automatically deletes an older take. Changing the reference creates another activity rather than mixing references. NEXT-STEP EVIDENCE A suggestion requires two different takes of the same phrase, recorded here with matching input configuration tokens/settings, an explicit same-conditions check, complete stable pitch rows and no clipping. A note must deviate by at least 25 cents in the same direction in both takes. The prompt identifies that note and the two readings, offers reference playback and an editable practice task. It is a listening prompt, not a diagnosis or an overall progress grade. If the signal/context is insufficient, or input is imported/unverifiable, compare by listening and write the next step. A new visit may have a new configuration token; matching device names or user confirmation alone does not override this gate. Measurements are recalculated from audio, not persisted as authoritative results. COMMON EXPORTS AND PRIVACY The HTML summary includes selected take labels, round goals/conditions/next steps and applicable feedback, without audio. It can be printed. Individual WAV exports contain the original canonical mono session audio, without comments. Both are explicit local downloads and do not sync to an account. The .hksession file is needed to listen and continue with full context. Shared text is unencrypted too. The reader renders rounds read-only. Its integration remains same-origin; no cross-origin account access, recording, remote URL import or classroom roster. INTEROPERABILITY The fields above document an interchange format that others can read/write with their own implementation. Such compatibility does not imply HertzKit endorsement or permission to redistribute HertzKit code, branding, site assets or third-party material. Existing rights and notices apply. Validate limits and audio hashes before playback, never execute file text, and preserve or explicitly reject unsupported versions rather than silently dropping data. COMPLETE DEMONSTRATION /assets/examples/session-lesson/integration-en.hksession Includes a reference, two teaching takes and timestamped feedback. The published client is same-origin only. Cross-domain, school-platform or branded use requires a separate integration and licensing agreement; no general code or third-party asset licence is granted by this example.