t3k-mushra - GitLite

KO | EN

gitlite — search

#terminal #self-hosted #machine-learning #llm #ai-agent #claude #golang #tailwindcss #cross-platform #java

t3k-mushra

(★ 9)

Web-based MUSHRA-style listening tests on audio samples.

파일 탐색기

ZIP 다운로드

- - generateSampleAudio.ts
  - localStore.ts
  - sampleTest.ts
- - env.d.ts
  - index.ts
  - Mushra.tsx
  - types.ts
- App.tsx
- index.css
- main.tsx
- vite-env.d.ts
.gitignore
A2Esr.tsx
index.html
LICENSE
package-lock.json
package.json
postcss.config.js
README.md
tsconfig.app.json
tsconfig.json
tsconfig.lib.json
tsconfig.node.json
vite.config.ts
vite.lib.config.ts
vitest.config.ts

# CDN으로 사용하기

jsDelivr

jsDelivr는 공개 GitHub 리포지토리를 별도 설정 없이 CDN으로 즉시 서빙합니다. 버전과 파일을 고르면 웹페이지에 바로 붙일 수 있는 링크와 예시 코드가 만들어집니다.

버전

파일

링크

예시

# 프로젝트 배지

npm version 바로가기

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

A React component for running web-based [MUSHRA](https://en.wikipedia.org/wiki/MUSHRA)-style listening tests on audio samples.

You provide audio as URLs and a callback for persistence. `t3k-mushra` handles the rest: gapless Web Audio playback with instant A/B switching, a draggable loop region, blind randomized ordering, 0–100 sliders, navigation, progress, and resumable sessions.

## Install

```bash
npm install t3k-mushra
```

`react` and `react-dom` (18 or 19) are peer dependencies. Import the stylesheet once, anywhere in your app:

```ts
import 't3k-mushra/style.css';
```

## Demo

The repo is a [Vite](https://vitejs.dev/) app that runs a complete example test using runtime-synthesized audio, so it works offline with no committed media:

```bash
npm install
npm run dev
```

Open the printed URL. The demo persists results to `localStorage` and lets you download them as JSON.

## Data model

A test is a two-level structure:

- **`MushraTest`** — `{ id?, title?, items }`.
- **`MushraItem`** — a group of pages shown together (e.g. one "tone"): `{ id, title?, description?, pages }`. Each item is a row on the overview.
- **`MushraPage`** — one rating screen: `{ id, description?, reference?, stimuli }`. A page has an optional reference plus the stimuli to rate.
- **`MushraStimulus`** — a single audio sample: `{ id, url }`. The `id` is the ground-truth key used in results and is never shown to the listener.
- **`MushraReference`** — an optional explicit reference: `{ url, label? }`. The `label` defaults to "Reference".

Within a page, stimuli are presented in a blind, randomized order (labeled A, B, C…). The order is deterministic per `participantId`, so a participant always sees the same layout. This makes sessions resumable and analysis reproducible.

### Flow

By default the participant sees:

1. An **instructions** dialog (`showWelcome`).
2. An **overview/index page** (`showIndex`) listing every item with its status and overall progress, plus a Start/Continue button. They can leave and resume here at any time.
3. A **page** screen: reference + blind stimuli with 0–100 sliders, a loop bar, and a numbered stepper. **"Submit & next"** saves the page and advances. On the final page of an item the button reads **"Submit"** and returns to the overview — unless every item is complete, in which case it goes to the completion screen. A "Back to overview" link is available at any time.
4. A **completion** screen (or your `renderComplete`, if provided) once every page of every item is submitted.

Set `showIndex={false}` to skip the landing page and step participants linearly through every page, ending on the completion screen.

## Usage

```tsx
import { Mushra } from 't3k-mushra';
import type { MushraTest, MushraPageResult } from 't3k-mushra';

const test: MushraTest = {
  id: 'codec-eval-2026',
  title: 'Codec evaluation',
  items: [
    {
      id: 'guitar-riff',
      title: 'Sample 1',
      description: 'Rate how closely each version matches the reference.',
      pages: [
        {
          id: 'clip-1',
          reference: { url: '/audio/guitar/reference.wav', label: 'Reference' },
          stimuli: [
            { id: 'opus-128', url: '/audio/guitar/opus-128.wav' },
            { id: 'mp3-128', url: '/audio/guitar/mp3-128.wav' },
            { id: 'anchor-3500', url: '/audio/guitar/anchor.wav' },
            { id: 'hidden-ref', url: '/audio/guitar/reference.wav' },
          ],
        },
      ],
    },
    // ...more items
  ],
};

function Study() {
  return (
    <Mushra
      test={test}
      participantId="participant-42"
      onSubmitPage={async (result: MushraPageResult) => {
        await fetch('/api/mushra', { method: 'POST', body: JSON.stringify(result) });
      }}
      onComplete={(results) => {
        console.log('Done!', results);
      }}
    />
  );
}
```

### Resuming a session

Pass previously saved results back in via `initialResults`. The component starts the participant on the first unanswered page and marks completed ones in the stepper:

```tsx
<Mushra test={test} participantId={id} initialResults={savedResults} onSubmitPage={save} />
```

## `<Mushra />` props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `test` | `MushraTest` | — | The test definition (required). |
| `participantId` | `string` | — | Seeds the deterministic blind order. Recommended. |
| `initialResults` | `MushraPageResult[]` | `[]` | Previously saved results, for resuming. |
| `onSubmitPage` | `(r) => void \| Promise<void>` | — | Called per page submit. Return a promise to show a spinner. |
| `onComplete` | `(results) => void` | — | Called once after the final page. |
| `randomizeStimulusOrder` | `boolean` | `true` | Blind-shuffle stimuli within each page. |
| `randomizeItemOrder` | `boolean` | `false` | Shuffle item order per participant. |
| `requireAllRated` | `boolean` | `true` | Warn before submitting if a slider was untouched. |
| `showIndex` | `boolean` | `true` | Show the overview/index landing page listing items + progress. |
| `showWelcome` | `boolean` | `true` | Show the instructions dialog first. |
| `showWalkthrough` | `boolean` | `true` | Show the guided interface tour. |
| `instructions` | `MushraInstructions` | sensible defaults | Custom welcome copy. |
| `walkthroughSteps` | `MushraWalkthroughStep[]` | sensible defaults | Custom tour steps. |
| `qualityBands` | `MushraQualityBand[]` | MUSHRA bands | Labels shown beneath each slider. |
| `labels` | `MushraLabels` | sensible defaults | Override UI strings. |
| `renderComplete` | `(results) => ReactNode` | built-in screen | Custom completion screen. |
| `className` | `string` | — | Extra class on the root element. |

## Results shape

`onSubmitPage` receives one `MushraPageResult` per page:

```ts
interface MushraPageResult {
  itemId: string;
  pageId: string;
  submittedAt: string; // ISO timestamp
  participantId?: string;
  ratings: {
    stimulusId: string;  // your ground-truth id
    blindLabel: string;  // what the listener saw, e.g. "C"
    score: number;       // 0–100
    rated: boolean;      // false if left at the default
  }[];
}
```

## Theming

All visuals are driven by CSS custom properties scoped to `.mushra-root` (see `src/lib/styles/theme.css`). Override them globally or on a wrapper to re-theme:

```css
.mushra-root {
  --mushra-accent: #8b5cf6;
  --mushra-radius: 0.375rem;
  --mushra-scale-from: #b91c1c; /* slider gradient bottom */
  --mushra-scale-to: #15803d;   /* slider gradient top */
}
```

## Lower-level building blocks

For a custom UI, the internals are exported too:

- `useAudioEngine(sources, resetOnPlay)` — the gapless, loopable Web Audio engine.
- `blindConditions(stimuli, { participantId, trialId, randomize })` — deterministic A/B/C labeling.
- `PreferencesProvider` / `usePreferences` — loop region and reset-on-switch preferences.
- `MushraIndex`, `TrialView`, `LoopBar`, `WelcomeDialog`, `Walkthrough`, `Button`.
- `clampLoopRegion`, `seededShuffle`, `fnv1a32`, `mulberry32`.

## Project layout

```
src/
  lib/                 # the reusable library
    Mushra.tsx         # the orchestrator component (main entry)
    types.ts           # public data model
    hooks/             # useAudioEngine (Web Audio)
    components/        # TrialView, LoopBar, dialogs, Button
    context/           # PreferencesProvider
    internal/          # prng, shuffle, loop-region, cx
    styles/            # theme.css + scoped CSS modules
  demo/                # demo-only: synthesized audio + localStorage store
  App.tsx              # demo app wiring
```

### Building the package

`npm run build` bundles `src/lib` (the published library) into `dist/` via Vite library mode (`vite.lib.config.ts`): an ES module (`dist/index.js`), a single stylesheet (`dist/style.css`), and type declarations (`dist/index.d.ts`). `react`, `react-dom`, and `lucide-react` are externalized. `npm run build:demo` builds the demo app into `dist-demo/`.

## Browser support

Requires the [Web Audio API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API) (all modern browsers). Audio is fetched and decoded with `fetch` + `decodeAudioData`, so stimulus URLs must be CORS-accessible.

## License

[MIT](./LICENSE)