OK Standby Jukebox

OK Standby Jukebox is a desktop-only Obsidian plugin for organizing music source links, audio files, videos, images, and zip exports into song notes.

It is designed for a practical workflow: put incoming files in source_docs, run one import command, and manage the results in songs.

What It Does

• Creates source_docs and songs automatically on first import.
• Imports source URLs from .txt and .url files.
• Moves .mp3, .mp4, .png, .jpg, and .jpeg assets into the songs folder.
• Extracts supported files from .zip archives before importing.
• Creates Markdown song notes with title, genre, status, created, source_url, youtube, and note_article.
• Updates existing song notes without overwriting unrelated content.
• Groups common asset suffixes such as _preview, _youtube, _short, _video, _frame, _cover, _thumbnail, _thumb, _ok_standby, and _loop_5s.
• Runs from the left ribbon, command palette, or optional auto-watch mode.

Before You Start

You need:

• Obsidian desktop.
• A vault where you want to manage music assets.
• The plugin release zip: ok-standby-jukebox-1.0.0.zip.

Important distinction:

• The plugin zip installs the plugin.
• Your music/material zip goes into source_docs after the plugin is enabled.

Manual Installation

1. Open or create an Obsidian vault first.
2. Close Obsidian, or keep it open and reload plugins after copying files.
3. In the vault, open the hidden .obsidian folder.
4. Inside .obsidian, create a folder named plugins if it does not already exist.
5. Inside plugins, create a folder named ok-standby-jukebox.

The final plugin folder path should be:

YOUR_VAULT/.obsidian/plugins/ok-standby-jukebox/

6. Extract all files from ok-standby-jukebox-1.0.0.zip into ok-standby-jukebox.

The files should be directly inside ok-standby-jukebox:

YOUR_VAULT/.obsidian/plugins/ok-standby-jukebox/manifest.json
YOUR_VAULT/.obsidian/plugins/ok-standby-jukebox/main.js
YOUR_VAULT/.obsidian/plugins/ok-standby-jukebox/styles.css

Avoid this nested structure:

YOUR_VAULT/.obsidian/plugins/ok-standby-jukebox/ok-standby-jukebox-1.0.0/manifest.json

7. Open Obsidian.
8. Go to Settings -> Community plugins.
9. Turn off Restricted mode if needed.
10. Enable OK Standby Jukebox from the installed plugins list.

First Run

Run the import once before adding materials.

You can run it in either way:

• Click the music icon in the left ribbon.
• Open the command palette and run OK Standby Jukebox: Import music assets.

On first run, the plugin creates these folders if they do not exist:

YOUR_VAULT/source_docs/
YOUR_VAULT/songs/

If there are no files yet, No music source files found. is normal.

Basic Usage

Put a text file in source_docs:

title: Test Song

https://example.com/music/source/xxxxxxxxxxxx

You can also add matching assets:

source_docs/
  Test Song.txt
  Test Song.mp4
  Test Song.png

Run Import music assets.

The result:

songs/
  Test Song.md
  Test Song.mp4
  Test Song.png

Zip Import

Put your material zip into source_docs:

source_docs/
  exported_materials.zip

Then run Import music assets.

The plugin extracts supported files, imports them, and deletes the zip after successful extraction.

Supported files inside zip archives:

• .txt
• .url
• .mp3
• .mp4
• .png
• .jpg
• .jpeg

Naming Tips

Files are grouped by their base song name.

These are treated as the same song:

Blue Ash Alley.txt
Blue Ash Alley_preview.mp4
Blue Ash Alley_youtube.mp4
Blue Ash Alley_cover.jpg
Blue Ash Alley_loop_5s.mp4

These may become separate notes because the base names differ:

loop short.mp4
loop video.mp4
loop video frame.jpg

After the suffix rules are applied, _short, _video, and _frame are grouped better when filenames use separators:

loop_short.mp4
loop_video.mp4
loop_video_frame.jpg

Settings

• Source folder: where incoming files are placed. Default: source_docs
• Songs folder: where notes and assets are stored. Default: songs
• Auto watch: periodically checks for new files.
• Watch interval: seconds between auto-watch checks.

Troubleshooting

The plugin does not appear

• Make sure you opened the correct vault.
• Make sure the plugin files are directly inside .obsidian/plugins/ok-standby-jukebox/.
• Make sure Restricted mode is off.
• Restart Obsidian or click the refresh icon in the installed plugins section.

The import says no files were found

• Put files into YOUR_VAULT/source_docs/, not into .obsidian/plugins.
• Make sure the file extensions are supported.
• If you changed plugin files, restart Obsidian or disable and enable the plugin again.

Files were split into several notes

Rename assets so they share the same base song name.

Good:

Song Name.mp4
Song Name_frame.jpg
Song Name_short.mp4

Risky:

short video.mp4
frame image.jpg

Existing notes did not merge after an update

The plugin does not automatically merge notes that were created before a naming-rule change. For a clean test, delete the test notes/assets from songs, reload the plugin, then import the same source files again.

Notes

This plugin is desktop-only because zip extraction uses Node.js APIs available in Obsidian desktop.

License

MIT License. See LICENSE.