@gui-chat-plugin/jinglescript

中文文档
1.2.1发布于 2026/11/09MITTypeScriptES Module近 30 天下载 4606

GUI Chat Protocol plugin for JingleScript: the manageJingleScript tool, with a player view for rendered jingles (waveform, cues, beats, notes).

原始使用文档

@gui-chat-plugin/jinglescript

A GUI Chat Protocol plugin for JingleScript. It offers the same single tool as the MCP server, manageJingleScript (actions getGuide, getSchema, listInstruments, getInstrument, checkScore, renderScore, composeScore), and adds a player view: a successful renderScore returns the jingle as data, and the view plays it with its waveform, beat grid, named cues (click one to jump there) and a lane of notes per track; effects with a length (risers, whooshes) show as bars. When the score has lyrics, the view shows them karaoke-style: the line being played and the next, each syllable filling in as its note plays. The audio and the music as MIDI (the library's scoreToMidi) can be downloaded from the view; the data also carries the score that was rendered. Every other action answers the LLM in text and shows no card.

Composing. composeScore has YuE2 write a melody and chords for lyrics, when it is set up on the host's machine (YUE2_PYTHON; its weights are non-commercial). The host's server waits 20–40 s for it, with no card. The score is saved as jinglescript/<fileName>.json through the host's files.byPath, and its path goes back to the LLM for renderScore; a host without files.byPath gets the score itself in the answer.

Sheet music, for teaching. renderScore takes three options for the view:

  • view: "waveform" (default) or "notation": sheet music drawn by OpenSheetMusicDisplay from the library's MusicXML, with a cursor on the note being played and a bar to seek. A score that sets meter, key or pickup carries its sheet music either way, and the view offers a Waveform / Sheet music switch; the MusicXML can be downloaded. The renderer is loaded only when sheet music is shown.
  • autoplay: true: the card starts playing when it appears. Only a fresh render does (one made in the last two minutes), and only once: the card remembers it in the result's viewState, so a chat reopened or replayed never plays old cards. When the browser wants a click first, the card says "Press play to listen". In a voice host that passes isAudioPlaying, it waits for the model's spoken answer to the render (up to 3.5 s after the card appears, or after the voice it appeared during), then until the voice has been quiet for 1.5 s, and pauses while the voice speaks again; once the user clicks play, the bar or a cue, the voice no longer pauses it.
  • autoplayDelay: n: wait n seconds (0–30) after the card appears before playing by itself, instead of waiting for the answer; in any host.
  • notifyWhenDone: true: when playback first reaches the end, the view sends the chat one message ("<title>" finished playing (12.0 s): the user has heard it to the end.) through the host's sendTextMessage, so the LLM can go on — ask a question, play the next exercise. Also remembered in viewState, so it is sent once. The view writes viewState through onUpdateResult with the whole result, as hosts expect.

The card before the audio. Rendering a long piece, or a vocal sung by NEUTRINO, takes seconds to minutes. In a host that gives the view a runtime (dispatch) and tells execute so with deferredAudio: true in its context, renderScore waits at most a second for the audio: a short jingle comes back finished as before; a longer one comes back at once as a pending card that shows the score, its lanes, cues, lyrics and sheet music, says at the top that the audio is rendering, and keeps play disabled. While NEUTRINO sings, it says how far it is ("Singing the vocal… 52 %", then "Mixing…"), asked once a second through the same dispatch. The view collects the finished audio through the host's dispatch (a request that reaches the same execute), saves it into the result with onUpdateResult (so the chat keeps it), and only then plays. autoplay waits for the audio in the same way, and counts as fresh from when it was ready; the voice rules above still apply. If the audio cannot be made after all, the card says why and, for a fresh render, tells the LLM once. A render kept for collection lives in the server's memory for 30 minutes after it finishes; a card replayed after a restart says it is gone. A host that does not set deferredAudio gets the finished card, as before.

A score can also be passed as a file (path instead of score). The plugin reads it through the host's files.byPath capability — the one presentDocument uses — so the host decides what a path may reach and what a relative path is relative to. A host that does not provide files.byPath to manageJingleScript gets an error asking for the score inline.

  • "@gui-chat-plugin/jinglescript" (main entry, Node): TOOL_DEFINITION, pluginCore (execute renders on the host's server, on a worker thread, so the server keeps answering). The audio is embedded as a data URI — MP3 when ffmpeg is on the server, otherwise 16-bit WAV — so no file serving is needed.
  • "@gui-chat-plugin/jinglescript/vue" (browser): plugin with viewComponent and previewComponent. It does not load the library. opensheetmusicdisplay is a dependency the host's bundler resolves (it is not bundled in), loaded on demand.

Adding it to MulmoTerminal

The library is a peer dependency (the host's server runs the tool), so a host installs both:

  1. yarn add jinglescript @gui-chat-plugin/jinglescript
  2. plugins/plugins.json: add "@gui-chat-plugin/jinglescript" to packages.
  3. src/plugins-registry.ts: import plugin from @gui-chat-plugin/jinglescript/vue and its style.css?inline, and add a PACKAGES entry. To show the card before a long render's audio, wrap the view in the runtime provider — wrapWithPluginRuntime("jinglescript", plugin.toolDefinition.name, viewOf(...)) — and on the server add manageJingleScript: { deferredAudio: true } to EXTRA_CONTEXT_BY_TOOL (server/infra/tools/plugins-registry.ts). Do both or neither: deferredAudio without the runtime leaves a long render's card without its audio. With neither, viewOf(...) alone works as before.
  4. common/toolGroups.ts: put manageJingleScript in the media group.
  5. Rebuild the frontend (yarn build) and restart MulmoTerminal (the server loads plugins at boot).

Development

yarn install
yarn typecheck   # vue-tsc, against the library's source
yarn test        # vitest, against the library's source
yarn build       # dist/: index.js (Node), vue.js + style.css (browser)
yarn definition  # regenerate src/definition.json from the library's zod schema
yarn demo-data && yarn demo   # a page with the player for three examples
yarn playground                # the GitHub Pages playground, rendering in the browser
yarn playground:build          # ../out/playground: what the Pages workflow deploys

版本与发布记录

@gui-chat-plugin/jinglescript 共发布 20 个版本,首次发布于 2026/10/09;过去 12 个月发布了 20 个版本。

版本发布日期距今
1.2.1latest2026/11/098 天前
1.2.02026/11/098 天前
1.1.02026/10/2820 天前
1.0.32026/10/2721 天前
1.0.22026/10/2721 天前
1.0.12026/10/2721 天前

关于 @gui-chat-plugin/jinglescript 的常见问题

@gui-chat-plugin/jinglescript 是什么?

GUI Chat Protocol plugin for JingleScript: the manageJingleScript tool, with a player view for rendered jingles (waveform, cues, beats, notes).

如何安装 @gui-chat-plugin/jinglescript?

在项目目录运行 npm install @gui-chat-plugin/jinglescript,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:vue(^3.5.43)、jinglescript(^1.2.1)、gui-chat-protocol(^2.3.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@gui-chat-plugin/jinglescript 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@gui-chat-plugin/jinglescript 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@gui-chat-plugin/jinglescript 可以商用吗?

@gui-chat-plugin/jinglescript 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@gui-chat-plugin/jinglescript 的下载量有多少?

根据 npm 官方下载统计,@gui-chat-plugin/jinglescript 在 2026/10/17 – 2026/11/15 这 30 天内被下载 4,606 次,日均约 154 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@gui-chat-plugin/jinglescript 还在维护吗?

最新版本 1.2.1 发布于 2026/11/09(8 天前);至今共发布 20 个版本,其中过去 12 个月发布了 20 个;首次发布于 2026/10/09。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。