# 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:

```text
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`:

```text
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:

```text
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:

```text
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`:

```text
title: Test Song

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

You can also add matching assets:

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

Run `Import music assets`.

The result:

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

## Zip Import

Put your material zip into `source_docs`:

```text
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:

```text
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:

```text
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:

```text
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:

```text
Song Name.mp4
Song Name_frame.jpg
Song Name_short.mp4
```

Risky:

```text
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](LICENSE).