HERTZKIT SESIONES 1.1 — FORMATO E INTEGRACIÓN Formatos 1 y 2 · Cliente del lector 1.0 Documentación para desarrolladores. Para el uso cotidiano, consultá /ayuda/#help-sessions. Demostración: /sesiones/integracion/ Lector: /sesiones/reproductor/ El lector abre referencias, intentos y observaciones. No graba, no accede a cuentas y no sube los archivos al servidor. Las descargas son datos portables, no certificados de autoría, identidad o rendimiento académico. FORMATO 1 Extensión .hksession; contenido JSON UTF-8, sin código ejecutable. Máximo 24 MiB. Campos principales: format="hertzkit-session", version=1, id, activityId, createdAt, updatedAt, language, title, goal, author, source, bpm, a4, instrument, notes, reference, takes, feedback. id identifica una copia de trabajo; activityId conserva la actividad de origen. Al abrir un archivo externo se crea una copia de trabajo con otro id, para no sobrescribir respuestas de personas diferentes. Una copia local abierta desde la biblioteca conserva su id para poder actualizarla explícitamente. notes contiene de 1 a 64 notas monofónicas. midi: 36–84 (Do2–Do6). start y duration se expresan en pulsos de negra, sin superposiciones. Máximo 32 pulsos y 20 segundos, a 40–240 BPM. a4: 400–480 Hz. reference contiene la referencia preparada con las notas revisadas y el banco grabado existente. Se exporta como WAV mono PCM de 16 bits. No se incluye todo el archivo de origen ni el banco completo. Cada recurso de audio contiene: codec="wav-pcm16-mono", rate, frames, sha256, data (base64). WAV: encabezado RIFF canónico de 44 bytes y datos PCM16 mono, 8–96 kHz. Hasta 20,5 segundos, incluyendo la breve cola de cierre. SHA-256 verifica todos los bytes WAV; no firma nombres, fechas ni declaraciones del archivo. source puede ser original-example, user-audio, user-midi o user-notes. Es una declaración sobre el origen del ejercicio, no una verificación de autoría. Tomas: hasta cuatro. Campos id, createdAt, alias, range{from,to}, input, audio, note. input contiene key, rate, gain, source, latencyMs. key es un código opaco de configuración de esta visita: nunca es el identificador del micrófono. Las tomas importadas tienen input.source="file". Devoluciones: hasta 30. Campos id, createdAt, author, takeId, seconds, body. takeId=null indica la referencia completa. seconds es relativo al audio elegido. body admite hasta 1000 caracteres. Los nombres o códigos son declarados. Se rechazan versiones no compatibles, campos inesperados, audio alterado, WAV inválidos, identificadores duplicados y observaciones sin una toma asociada. El archivo no está cifrado ni firmado y no demuestra que nunca se haya enviado. Las mediciones se recalculan desde el audio cuando se solicitan; no se conserva una calificación automática como autoridad. Comparar requiere mismo fragmento, configuración compatible, confirmación del usuario y lecturas suficientes. GUARDADO LOCAL Las copias se conservan únicamente en este navegador, al pulsar Guardar. Hasta diez copias y 100 MiB en conjunto. No sincroniza con Mi cuenta ni Proyectos. Si falla el guardado, la sesión permanece en memoria y se puede descargar. Eliminar una copia local no elimina descargas ni datos de otras herramientas. CLIENTE DEL LECTOR 1.0 Archivo: /assets/js/sessions/session-client.js Constructor: new HKSessionsReaderClient(iframe, {timeout:15000}) Métodos: ready() espera a que el lector responda load(file) abre un File/Blob de hasta 24 MiB play("reference") reproduce la referencia; también acepta un takeId pause() pausa seek(seconds) cambia de posición en el audio actual, de 0–20,5 s destroy() retira escuchas y cancela solicitudes pendientes Los métodos asíncronos devuelven promesas. Ejemplo: const lector = new HKSessionsReaderClient(document.querySelector('iframe')); await lector.load(entrada.files[0]); await lector.play('reference'); await lector.pause(); await lector.seek(1.5); lector.destroy(); La integración publicada admite únicamente el mismo origen. No habilita dominios externos, micrófono, URLs de audio remotas ni HTML arbitrario. Para otra web se requiere una instalación autorizada y alojada en su propio origen. El lector alojado en HertzKit no admite integraciones entre dominios. Las reglas de reproducción del navegador pueden exigir un primer gesto dentro del lector. PROTOCOLO POSTMESSAGE Se comprueban event.origin===location.origin y event.source contra el marco o padre esperado. El origen de destino debe ser exacto: nunca usar "*". requestId: texto de hasta 64 caracteres para vincular solicitudes y respuestas. Comandos: hertzkit.sessions.ping hertzkit.sessions.load {file} hertzkit.sessions.play {takeId:"reference" | identificador de toma} hertzkit.sessions.pause hertzkit.sessions.seek {seconds} Respuestas, con el prefijo hertzkit.sessions: ready{version:1}, loaded{takes,feedback}, playing, paused, position{seconds}, error{code}. El lector informa cantidades; no transmite nombres ni observaciones. El archivo se copia entre ventanas del mismo origen, sin una subida de red. TRASLADO DESDE PROYECTOS Un botón explícito abre Preparar en otra pestaña y ofrece copiar solamente título, objetivo y BPM. Canal temporal del navegador con código aleatorio, duración máxima 30 segundos. No usa localStorage ni envía textos en la URL o al servidor. El usuario aplica los datos recibidos. El proyecto permanece abierto; no se trasladan tareas, notas, grabaciones ni datos de cuenta, ni se guarda por detrás. DERECHOS Y COMPATIBILIDAD El código original conserva sus derechos. Esta documentación no concede por sí sola una licencia para redistribuir comercialmente el sitio completo. Se mantienen los avisos de los componentes y bancos CC0 existentes. Los ejemplos son ejercicios originales. Cada usuario debe contar con los permisos necesarios para usar y compartir sus grabaciones. No es un estándar de intercambio de DAW. La grabación requiere HTTPS o localhost, Web Audio y AudioWorklet compatibles. Importación, escucha y guardado dependen del navegador y de su espacio disponible. El uso offline requiere preparar y probar antes el paquete sin conexión. EXTENSIÓN DE CONTINUIDAD — FORMATO 2 El lector actual abre formatos 1 y 2. El protocolo postMessage sigue en versión 1; ready añade fileVersions:[1,2] y loaded incluye el número de rondas (rounds). Los archivos anteriores no se reescriben automáticamente. Organizar en rondas actualiza esa copia a versión 2. Un lector anterior debe rechazarla, no descartar las rondas silenciosamente. La copia compatible elimina journey y usa versión 1; conservá el original versión 2 para no perder objetivos ni contexto. Versión 2 mantiene los campos raíz y límites del formato 1, y añade journey: {activeRound, rounds, roles:{baseline, final, retest}} Cada rol es un id de intento existente distinto o null. rounds tiene 1–12 entradas: {id, createdAt, label, goal, conditions, takeIds, nextStep, focus} label: 1–80 caracteres; goal: 1–1000; conditions: 0–500; nextStep: 0–1000. focus: null o {from,to}, índices de notas desde cero en la referencia compartida. createdAt: ISO UTC canónico, declarado por el equipo; no es una fecha certificada. Cada intento pertenece exactamente a una ronda. Todos los takeIds y activeRound deben existir. Las rondas no duplican audio: comparten referencia y el límite total de cuatro intentos, 30 comentarios y 24 MiB por archivo. Al quitar o excluir intentos, se limpian sus vínculos y roles; los objetivos y próximos pasos permanecen. Nunca se elimina una toma antigua automáticamente. Cambiar la referencia crea otra actividad; no mezcla referencias en un recorrido. EVIDENCIA DEL PRÓXIMO PASO Requiere dos intentos distintos del mismo fragmento, grabados aquí con el mismo token/configuración de entrada, confirmación explícita de condiciones, lectura estable de todas las notas y ausencia de saturación. Una nota debe mostrar al menos 25 cents en el mismo sentido en ambas tomas. La sugerencia identifica nota y lecturas, permite escuchar la referencia y propone una tarea editable. Es una propuesta para escuchar y practicar, no un diagnóstico ni una nota general. Si faltan señal o contexto, o las tomas son importadas/no verificables, se invita a comparar por escucha y escribir el próximo paso. Una visita nueva puede tener otro token de entrada; nombres de dispositivos o confirmación no evitan ese control. Las mediciones se recalculan; no se conservan como resultados certificados. EXPORTACIONES Y PRIVACIDAD El resumen HTML incluye etiquetas de intentos elegidos, objetivos, condiciones, próximos pasos y devoluciones correspondientes, sin audio. Se puede imprimir. Cada WAV conserva el audio mono canónico de la sesión, sin comentarios. Son descargas locales explícitas y no se sincronizan con una cuenta. Para escuchar y continuar con todo el contexto se necesita el .hksession. Los textos tampoco están cifrados. El lector muestra las rondas sin permitir su edición. La integración continúa limitada al mismo origen: sin grabación, acceso a cuentas desde otros sitios, importación de URLs remotas ni gestión de alumnos. INTEROPERABILIDAD Los campos documentan un intercambio que puede leerse/escribirse con una implementación propia. Ser compatible no implica aval de HertzKit ni permiso para redistribuir su código, marca, sitio o material de terceros. Siguen vigentes los derechos y avisos correspondientes. Validá límites y hashes antes de reproducir; nunca ejecutes los textos y rechazá versiones incompatibles en lugar de perder datos. DEMOSTRACIÓN COMPLETA /assets/examples/session-lesson/integration-es.hksession Incluye referencia, dos intentos didácticos y devolución con tiempo. El cliente publicado se limita al mismo origen. Un uso en otro dominio, plataforma escolar o producto de marca requiere una integración y un acuerdo de licencias; este ejemplo no otorga una licencia general del código ni de recursos de terceros.