@neurall-io/player

npm install @neurall-io/player

import { NeurallPlayer } from '@neurall-io/player/react'

<NeurallPlayer
  projectId="0a7c2e91-3b4d-4f5e-8a6b-7c8d9e0f1a2b"
  getToken={() => fetch('/api/neurall-token?project=0a7c2e91-...').then((r) => r.json())}
  ref={player}
  onReady={({ duration, fps }) => ...}
  onTime={(seconds) => setPlayhead(seconds)}
  onDraft={({ dirty, canUndo, saving }) => setToolbar({ dirty, canUndo, saving })}
/>

player.current.play()
player.current.seekTo(3.2)
player.current.edit([{ kind: 'caption', index: 14, text: 'Luna Nails' }])   // drawn at once, not sent
player.current.undo()
player.current.redo()
await player.current.save()      // the whole draft in one call
player.current.discard()         // or drop it

Edits live in a draft in the browser until save(). Every edit is one the page can draw at once: a reel's caption words and look, a show's text, music, pictures, accent and moments. What a video is made with (ratio, variant, voice, a reel's brand colour) is chosen when it is generated. A save sends the edits with the save they started from; when the project was saved from somewhere else in between, save() throws SaveConflict (carrying the current project) and keeps the draft.

The editor is in the player

Every edit is a function on the handle, and each one is a step of the draft, so undo, redo and save need nothing more. What an editor reads (the caption on screen, a show's moments and the fields each owns, the pictures a scene draws, the handles of the current cut) comes off the draft through the same handle. The document's shape is the kit line's, so the kit answers those questions and the loader never has to change when a rig does.

// what the panels read, off the draft
player.getScenes()                    // [{ index, label, line, startSeconds, durationSeconds }]
player.getSceneAt()                   // { index, sceneFrame } under the playhead
player.getCaptions()                  // a reel's lines, each with its transcript word indices
player.getCaptionAt(seconds)
player.getMoments()                   // a show's moments: label, range, fields [{ key, label, value, page?, target? }]
player.getShowSettings()              // { music, accent }
player.getPictures(scene)             // [{ ref, width, height, box, original? }]
player.getHandles()                   // the current cut's handles and tools (swatch, caption placements)
player.getMedia() / await player.refreshMedia()
player.describeDraft()                // one line per unsaved change

// the operations
player.fixWord(14, 'Luna')
player.setMomentText(3, 'price', '$29', page)
player.setText('offer', 'cta', 'Get lifetime access')
player.setMusic(0.3)                  // coalesced: one undo step per slider drag
player.setAccent('#ff5a2d')
player.dropMoment(3)
player.showPicture(shot, page, item)  // an item of getMedia()
await player.replacePicture(scene, ref, item)   // fitted to the spot on the server, then swapped
player.restorePicture(scene, ref)
player.placeCaptions('column-left')
player.setSwatch('#202020')
player.removeHandle(handle)
player.resetLook()

The moving things generate their own edit. A drag on a handle is a gesture: preview while the pointer moves, one undo step on release, in composition pixels (toComposition reads a pointer back into them).

const drag = player.startDrag(handle, 'move' | 'resize' | 'rotate', x, y, corner?)
drag.moveTo(x, y)
drag.end(x, y)     // or drag.cancel()

The controls are inside the element

<NeurallPlayer projectId="..." getToken={...} controls keyboard editing={mode} onEditing={setMode} />

controls draws the bar under the picture: play, time, the scrub track with a dot per scene, the length, sound, full screen. As an object it says what is in it and how it looks:

controls={{
  items: ['play', 'scrub', 'scenes', 'mute', 'fullscreen', 'look', 'draft', { id: 'share', mount: (el, player) => { ...; return () => {} } }],
  position: 'below' | 'overlay',
  theme: { accent: '#ff5a2d', ink: '#fff', bar: '#000', height: 40, radius: 10 },
  labels: { editLook: 'Adjust', save: 'Publish' },
  scenes: { label: (s) => `Part ${s.index + 1}`, line: false },
}}

look is the Edit look toggle and draft the Save, Undo, Redo and Discard group; both are opt in. A slot mounts your own control in the bar's flow. Every colour is a custom property (--np-accent, --np-ink, --np-bar, ...) on the element, so a stylesheet can set them too. keyboard makes space play and pause and the arrows step while the element has the focus.

Editing is a mode. setEditing(false | true | 'look') and getEditing(), with onEditing when it moves. false plays only and refuses every operation (reported through onError); true takes fields and words; 'look' mounts the look editor over the picture, pauses, and turns click-to-play off. It starts closed when the token cannot save (scope: ['read']) or the project is not ready, and opens to editing (default true) once it can. The bar's look toggle and your own buttons all go through setEditing, so they cannot disagree.

Without React: defineElement() registers <neurall-player project-id="...">, with the same methods and the same events (neurall:ready, neurall:time, neurall:draft, neurall:editing, ...); an editing attribute sets the mode and element.player is the full handle. Pure renderer: pass document and media instead of a projectId and keep every API call on your own backend.

The package holds no credentials. Your server mints the token (POST /v3/video-projects/:id/embed-token) and getToken hands it to the player, which refreshes it a minute before it expires and retries once on a 401. The default token reads and saves its one project; mint it with scope: ['read'] for a page that only plays.