Scene sharing

Scenes travel two ways: as portable .hibiki.zip archives you hand to a friend, or as reference recipes in a community registry you browse from inside the app.

Installing community scenes

Ready-made scene packs (bundled audio)

The quickest way to a playable soundboard. The hibiki-scene-packs repository publishes .hibiki.zip packs that include both the scene and its sound files, all public domain (CC0) with one CC BY 4.0 door sound credited inside each pack.

1. Download a pack from the latest release: Cozy Tavern, Deep Forest Trail, Dungeon Crawl, Battlefield Clash, Stormy Night at the Inn, Haunted Crypt, High Seas Voyage, or Market Day.
2. Open the Scenes tab in Hibiki and click Import.
3. Select the zip. The scene and its sounds land in your library, ready to play.

Every pack ships a CREDITS.txt listing each track’s author, source URL and license. The same scenes also exist as reference-only entries in the community registry below.

Browse the community registry

1. Open the Scenes tab in Hibiki.
2. Click Browse in the scene actions bar.
3. A modal opens with all scenes from the community registry. Search by name, author, tag, or description.
4. Click Install on any scene. Hibiki creates the scene in your library with all track references.

Since registry scenes are reference-only (no bundled audio), installed tracks will show a missing badge until you add matching sound files to your library. Hover over the badge to see source hints for where to find the audio.

The registry index is cached for 24 hours. Click Refresh in the modal to force-update.

Import a local file

If someone sends you a .hibiki.zip file:

1. Open the Scenes tab.
2. Click Import and select the zip file.

How the registry works

The community registry lives in the registry/ directory of the Hibiki repo. Each scene is a single JSON file containing the full scene definition — track names, volumes, and source references. No audio files are stored or distributed.

When you click Install in the Browse modal, Hibiki reads the scene definition directly from the registry and creates a local scene. There is no zip download — the JSON entry is the scene.

Each track includes a source block that tells the user where to find the audio:

{
  "soundName": "Crackling Fire",
  "source": {
    "name": "Crackling Fireplace",
    "url": "https://freesound.org/people/example/sounds/12345/",
    "note": "Any fireplace loop works"
  }
}

Bundled exports (personal use)

When you export a scene from Hibiki for personal sharing (e.g. sending a zip to a friend), the export includes bundled audio files. This is fine for direct sharing — the registry restriction only applies to scenes submitted to the community registry.

Creating and sharing a scene

1. Build the scene

Create a scene in Hibiki as you normally would: add music, ambience, and effects tracks, set volumes and loop options.

2. Create the registry entry

Create a JSON file with your scene definition. Each track needs a source block describing where to find the audio.

Example entry:

{
  "name": "Dark Tavern",
  "slug": "dark-tavern",
  "description": "A moody tavern with crackling fire and distant murmurs.",
  "author": "YourName",
  "version": "1.0.0",
  "tags": ["tavern", "social", "ambient"],
  "category": "environment",
  "audioBundled": false,
  "createdAt": "2026-03-18T00:00:00Z",
  "updatedAt": "2026-03-18T00:00:00Z",
  "scene": {
    "music": [
      {
        "soundName": "Tavern Theme",
        "volume": 70,
        "loop": true,
        "source": {
          "name": "Medieval Tavern Music",
          "url": "https://freesound.org/people/example/sounds/12345/",
          "note": "Any calm tavern music works"
        }
      }
    ],
    "ambience": [
      {
        "soundName": "Crackling Fire",
        "volume": 50,
        "enabled": true,
        "source": {
          "name": "Fireplace Crackle Loop",
          "url": "https://freesound.org/people/example/sounds/67890/",
          "note": "Any fireplace or campfire loop"
        }
      }
    ],
    "effects": []
  }
}

Key fields:

• slug — URL-safe identifier, must match the filename (e.g. dark-tavern.json).
• description — A short sentence describing the mood/setting.
• author — Your name or handle.
• tags — Keywords for discovery (e.g. combat, tavern, forest, horror).
• source.name — The name or title of the audio the user should look for.
• source.url — A link to where the audio can be found (optional but helpful).
• source.note — A hint if the exact track doesn’t matter (e.g. “any rain loop works”).

3. Submit to the community registry

1. Fork the Hibiki repo.
2. Create a file at registry/scenes/<your-username>/<scene-slug>.json with your scene entry.
3. Open a pull request against the Hibiki repo. The Registry CI workflow validates your entry automatically (schema check, slug uniqueness, track source blocks).
4. Once merged, the index is rebuilt and the scene appears in the Browse modal for all Hibiki users.

Example scenes

The registry ships eight reference scenes under registry/scenes/PhyberApex/, starting with cozy-tavern.json. They demonstrate all required fields, show how to structure tracks with source blocks across music, ambience, and effects, and spell out each track’s license in the source.note. Use one as a template when creating your own submission. The same eight scenes are available with bundled audio as scene packs.

Registry entry reference

Scene fields

Track fields

Each track in scene.music, scene.ambience, or scene.effects:

Registry validation

The registry has a JSON Schema at registry/schema/scene-entry.schema.json that all entries must conform to. You can validate locally before submitting:

pnpm registry:validate

CI runs this automatically on PRs that touch registry/scenes/. It checks:

• All required fields present and correctly typed
• audioBundled is false (no bundled audio allowed)
• Slug matches the filename and is URL-safe
• Version is valid semver
• Every track has a source block with at least a name
• Scene has at least one track
• No duplicate slugs across the registry