# Build a musical Word document with SuperDoc

SuperDoc Sessions asks: how can a real, editable DOCX perform a song while someone keeps typing?

The app uses **superdoc 2.29.0**, **docx 9.7.1**, **Vite 8.3.6** and **openai 7.13.0**. Start with [the Editor quickstart](https://docs.superdoc.dev/editor/quickstart/) and [custom UI setup](https://docs.superdoc.dev/editor/custom-ui/overview/). Check the installed version before reusing an API example.

## What SuperDoc supplies

The native DOCX renderer, pages, editable paragraphs, text selection, formatting, tables, images, comments, tracked revisions and Word export. Public UI commands and subscriptions connect custom controls to the engine. Document targets identify the passages that the app writes, formats and follows.

```js
import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';
const superdoc = new SuperDoc({
  selector: '#editor',
  document: '/blank.docx',
  documentMode: 'editing',
  ui: { toolbar: false, comments: false },
  onReady() { /* Enable your application controls here. */ }
});
```

After onReady, a timed application action writes into the real document:

```js
const { paragraph } = await superdoc.activeEditor.doc.create.paragraph({
  at: { kind: 'documentEnd' }, text: suppliedLyric
});
```

These snippets are integration excerpts, not a complete music app. Supply an editor container, a blank DOCX and your own playback adapter. The running Jukebox app is the complete demonstration.

## What the application supplies

The personalized CD opening, player, music bar, song palette, timing pipeline and executable composition director. OpenAI transcription/alignment and web research run on the server. LRCLIB can provide matched timed lyrics. Optional GIPHY media retains provenance and falls back to original animation.

Drive the entire performance from the actual playback clock. Keep audio paused during CD spin-up. Wait for vocal onset before writing lyrics. Use selective character bursts within sung words, quiet passages and song-specific set pieces. Cache transcription separately from creative direction so a remix does not require transcription again.

SuperDoc's native paragraphs and tables stay editable. Light, animated paper, GIF/video renditions and FFT meters are application visual layers anchored to those native targets. The optional EQ uses real Word table cells with paint-only audio bars at selected musical moments. A real Word header can contain the table and repeat it on pages; it scrolls with each page. Body placement is useful when the header would be outside the viewport. Do not invent audio levels for cross-origin embedded YouTube playback.

Use [selection and viewport APIs](https://docs.superdoc.dev/editor/custom-ui/selection-and-viewport/) to follow paragraph targets without moving the caret. Preserve human edits. Native comments and tracked revisions can have a custom review panel through [the headless UI controller](https://docs.superdoc.dev/editor/custom-ui/overview/).

## Export and portability

[Export the edited DOCX](https://docs.superdoc.dev/editor/export-options/) through SuperDoc. Native text, supported formatting, tables, images and review content belong to the file. Sound playback and canvas animation remain application behavior, not a music video embedded in Word. Download the separate executable session plan from Song information.

## Build your own

Ask your coding agent to create an app with this architecture. Keep all model credentials server-side. Use uploaded audio or a visible YouTube embed driven by its real clock; Spotify links are metadata references. Resolve recording/version/duration before choosing timed lyrics. Never invent lyrics or describe untimed text as precise alignment. Support reduced motion, keyboard controls and desktop/mobile fit-width layouts.

Verify vocal onset, pause, seek, replay, buffering, editing during playback, stable caret, stanza spacing, actual native table contents and Word export. Keep the EQ optional and brief. Validate every composition action against a supported renderer operation. The hosted architecture below keeps the editor in the browser and paid work on the server.

See [the working brief](/BRIEF.md), [featured composition](/composition.json), [featured session transcript](/session.md), and [agent discovery index](/llms.txt). Private audio, lyrics, sources and credentials are excluded from the copyable implementation prompt.

## Restore a saved performance

DOCX export also saves a native custom XML part, written through `doc.customXml.parts.create()` or `patch()`. Its root namespace is `https://superdoc.dev/sessions/v1`. The payload includes a stable session ID, format version, saved time, YouTube recording URL when available, exact composition and variation seed, palette, lyric alignment, page targets and playback position. Credentials and audio bytes are not embedded.

Choose **New song → Open a saved session DOCX** to reopen it. The app reads and validates the metadata, restores the native Word file and saved document targets, then reinstates the composition without running AI direction again. Typed edits stay in the DOCX. A hosted recording replays through its scoped read capability until the original seven-day expiry, even in another browser. After expiry, select the same original audio file or saved visible YouTube recording. Older laptop-local exports may require reconnecting the original recording. Recording availability and external media still depend on their providers. Structural changes made outside Sessions can invalidate the saved paragraph map; the app reports that rather than guessing where to write.

## Cloudflare hosting

The public deployment targets https://jukebox.superdoc.dev. A Cloudflare Worker routes to an isolated Node container, and a Durable Object coordinates anonymous quotas, job progress and the AI admission budget. Private R2 storage holds recordings, timing and creative caches for seven days. Requests enforce expiry even before lifecycle cleanup runs. Audio access uses a recording-specific capability; sharing an exported session DOCX shares that access until expiry.

Creation and Remix use server-validated Turnstile. The OpenAI key is a runtime server secret, excluded from client bundles, images and DOCX metadata. The initial AI admission budget is $25 per UTC day. This is separate from hosting charges and other products using the same key. Uncertain AI calls retain their conservative reservation and are not retried automatically. Pausing creation leaves playback, editing and DOCX restoration available.

Clear YouTube artist/title metadata is matched directly against the lyric catalog before using AI identification. Repeated lookup and recording metadata are cached. Independent artwork searches run concurrently; the creative research and exact-recording alignment remain intact.

Public YouTube audio and completed timing are cached separately from each visitor’s creative work. A fresh import fetches recording metadata and audio together. Turnstile verification starts when New song opens, in parallel with entering the link, and one verified workflow covers version lookup and creation. No audio or AI work begins until submission.

If transcription omits supplied lyric lines, a matching LRCLIB timing reference can recover line boundaries only when at least eight recording anchors and most catalog lines agree. Match repeated choruses in sequence. Mark recovered boundaries as catalog-calibrated, preserve the supplied text and reference URL, and do not claim word timing for those lines.