Recording

The <fortyfour-recording> element is the core primitive that everything else connects to. It is a hidden element that manages audio state, loads recording data, and handles playback. You never see it on the page, but every other primitive depends on it.

Basic usage

Give it an id and a recording-id. Then link other primitives to it using the for attribute.

HTML

<fortyfour-recording
  id="my-recording"
  recording-id="YOUR_RECORDING_ID"
  preload="metadata"
></fortyfour-recording>

<fortyfour-play-button for="my-recording"></fortyfour-play-button>
<fortyfour-bar-waveform for="my-recording"></fortyfour-bar-waveform>
<fortyfour-duration for="my-recording"></fortyfour-duration>

The recording element fetches the audio data and metadata from the 44 API. All connected primitives automatically update when the state changes.

Preload strategies

The preload attribute controls when data is loaded.

Value	What it loads	When to use
`none`	Nothing until play is clicked	Multiple recordings on a page. Saves bandwidth.
`metadata`	Waveform, duration, transcription	You want to show the waveform before play.
`auto`	Metadata and the audio file	You need instant playback with zero delay.

The default is none. For most cases, metadata is a good choice because it lets you show the waveform and duration right away without loading the full audio file.

HTML

<fortyfour-recording
  id="rec"
  recording-id="YOUR_RECORDING_ID"
  preload="metadata"
></fortyfour-recording>

Attributes

Attribute	Type	Default	Description
`recording-id`	string	required	The recording ID to load
`api-host`	string	`api.44.audio`	API host for fetching recording data
`preload`	string	`none`	Preload strategy: `none`, `metadata`, or `auto`

Properties

These are read-only JavaScript properties on the element.

Property	Type	Description
`state`	string	Current state (see state table below)
`duration`	number	Total duration in milliseconds
`currentTime`	number	Current playback position in milliseconds
`metadata`	object	Recording metadata: `{ waveform, transcription, translation, words }`

States

State	Description
`idle`	Initial state, nothing loaded
`loading`	Fetching metadata from the API
`ready`	Metadata loaded, ready to play
`playing`	Audio is playing
`paused`	Audio is paused
`ended`	Playback reached the end
`error`	Something went wrong

Methods

JavaScript

const recording = document.getElementById("my-recording");

recording.togglePlay(); // Toggle between play and pause
recording.play();       // Start playback
recording.pause();      // Pause playback
recording.seek(5000);   // Seek to 5 seconds (time in milliseconds)

Method	Description
`togglePlay()`	Toggle between playing and paused states
`play()`	Start playback
`pause()`	Pause playback
`seek(timeMs)`	Seek to a position in milliseconds

Events

All events bubble up through the DOM. You can listen on the element directly or at a higher level.

JavaScript

const recording = document.getElementById("my-recording");

recording.addEventListener("loadedmetadata", () => {
  console.log("Duration:", recording.duration);
  console.log("Transcription:", recording.metadata.transcription);
});

recording.addEventListener("play", () => {
  console.log("Playback started");
});

Event	Description
`loading`	Started fetching metadata
`loadedmetadata`	Metadata (waveform, transcription, duration) loaded
`play`	Playback started
`pause`	Playback paused
`timeupdate`	Playback position changed
`ended`	Playback reached the end
`error`	An error occurred loading or playing