release v0.3.0

.github/workflows/release.yml

@@ -0,0 +1,60 @@
+name: Create Release from Tag
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Extract version from tag
+        id: version
+        run: |
+          VERSION=${GITHUB_REF#refs/tags/v}
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+
+      - name: Extract changelog for version
+        id: changelog
+        run: |
+          VERSION=${{ steps.version.outputs.version }}
+
+          # Extract the changelog section for this version
+          # Looks for ## [x.y.z] and captures until the next ## [
+          CHANGELOG=$(awk -v ver="$VERSION" '
+            /^## \[/ {
+              if (found) exit
+              if (index($0, "["ver"]")) {
+                found=1
+                next
+              }
+            }
+            found {print}
+          ' CHANGELOG.md)
+
+          # If no changelog found, use default message
+          if [ -z "$CHANGELOG" ]; then
+            CHANGELOG="Release v$VERSION"
+          fi
+
+          # Write to file to preserve newlines
+          echo "$CHANGELOG" > release_notes.md
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          name: v${{ steps.version.outputs.version }}
+          body_path: release_notes.md
+          draft: false
+          prerelease: ${{ contains(steps.version.outputs.version, '-') }}
+          generate_release_notes: false
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

CHANGELOG.md

@@ -0,0 +1,135 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+> **Note**: This library is published at [ISMIR 2025 LBD](https://ismir2025program.ismir.net/lbd_459.html). See [Citation](#citation) for reference.
+
+
+## [0.3.0] - 2025-12-02
+
+### Added
+
+- Appearance API and solo mode for single MIDI visualization
+- Tempo control with popover input for precise BPM adjustment
+- Flexible MIDI export options
+- Pitch hover indicator to piano roll
+- VS Code extension support (`wave-roll-solo`) for viewing MIDI files directly in the editor
+- GitHub Actions workflow for automated release creation from tags
+
+### Changed
+
+- Improved MIDI export and settings UI
+- Improved audio synchronization and tempo handling
+- Improved tempo handling for multi-MIDI playback
+- Enhanced piano roll pitch hover and piano key visuals
+- Improved UI controls and audio handling
+
+### Refactored
+
+- Refactored settings modal
+- Removed console logs and stabilized the tests
+
+
+## [0.2.5] - 2025-10-09
+
+### Changed
+
+- Updates package version and demo notebook name
+
+## [0.2.4] - 2025-10-09
+
+### Added
+
+- Jupyter notebook demo with usage examples
+- Dynamic file config for Google Colab
+
+### Changed
+
+- Improved audio file handling and UI
+- Updates label to reflect single WAV file limit
+
+## [0.2.3] - 2025-09-24
+
+### Fixed
+
+- False Negative highlight mode
+
+## [0.2.2] - 2025-09-22
+
+### Added
+
+- Legacy highlight modes for compatibility
+- Piano roll zoom in mobile
+- Performance analysis
+
+### Fixed
+
+- FP highlight mode
+- TP highlight mode
+
+## [0.2.1] - 2025-09-21
+
+### Fixed
+
+- Correct sample file paths for GitHub Pages deployment
+
+## [0.2.0] - 2025-09-21
+
+### Added
+
+- Read-only mode (`readonly` attribute) to disable file addition/deletion
+- Standalone demo with drag-and-drop file upload interface
+- UMD and ES module CDN distribution
+- Custom web component `<wave-roll>` for easy embedding
+
+### Changed
+
+- Refactored examples and updates deployment
+- Updated import path and links in documentation
+- Renamed `displayName` to `name` for file labeling
+
+### Removed
+
+- Unused v1 player codes
+- Unused comments and packages
+
+## [0.1.5] - 2025-08-06
+
+### Fixed
+
+- Marker error
+
+## [0.1.4] - 2025-08-06
+
+### Changed
+
+- Node versions in `npm_publish.yml`
+
+## Citation
+
+If you use WaveRoll in your research, please cite:
+
+```bibtex
+@inproceedings{waveroll2025,
+  title={WaveRoll: JavaScript Library for Comparative MIDI Piano-Roll Visualization},
+  author={Park, Hannah and Jeong, Dasaem},
+  booktitle={Proceedings of 26th International Society for Music Information Retrieval Conference (ISMIR)},
+  year={2025}
+}
+```
+
+---
+
+[Unreleased]: https://github.com/crescent-stdio/wave-roll/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/crescent-stdio/wave-roll/compare/v0.2.5...v0.3.0
+[0.2.5]: https://github.com/crescent-stdio/wave-roll/compare/v0.2.4...v0.2.5
+[0.2.4]: https://github.com/crescent-stdio/wave-roll/compare/v0.2.3...v0.2.4
+[0.2.3]: https://github.com/crescent-stdio/wave-roll/compare/v0.2.2...v0.2.3
+[0.2.2]: https://github.com/crescent-stdio/wave-roll/compare/v0.2.1...v0.2.2
+[0.2.1]: https://github.com/crescent-stdio/wave-roll/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/crescent-stdio/wave-roll/compare/v0.1.5...v0.2.0
+[0.1.5]: https://github.com/crescent-stdio/wave-roll/compare/v0.1.4...v0.1.5
+[0.1.4]: https://github.com/crescent-stdio/wave-roll/releases/tag/v0.1.4

README.md

@@ -8,6 +8,7 @@
 
 ![NPM Version](https://img.shields.io/npm/v/wave-roll)
 ![NPM License](https://img.shields.io/npm/l/wave-roll)
+[![arXiv](https://img.shields.io/badge/arXiv-2511.09562-b31b1b.svg)](https://arxiv.org/abs/2511.09562)
 
 ![Screenshot of WaveRoll](./wave-roll.png)
 
@@ -165,6 +166,18 @@ IFrame(src='https://crescent-stdio.github.io/wave-roll/standalone.html', width='
 
 This is particularly useful for music information retrieval (MIR) research, allowing you to visualize and compare transcription results directly in your analysis notebooks.
 
+### VS Code Extension
+
+Use WaveRoll directly in VS Code with the **Wave Roll Solo** extension:
+
+- Open any `.mid` or `.midi` file to view it as an interactive piano roll
+- Play MIDI files with built-in Tone.js synthesis
+- Adjust tempo and export MIDI with modified tempo
+
+**Installation**: Search "WaveRoll Solo" in VS Code Extensions marketplace
+
+**GitHub**: [crescent-stdio/wave-roll-solo](https://github.com/crescent-stdio/wave-roll-solo)
+
 ## API
 
 ### Attributes
@@ -206,23 +219,72 @@ interface FileItem {
   path: string;   // URL or relative path to the file
   name: string;   // Display name shown in UI
   type?: "midi" | "audio"; // Defaults to "midi" when omitted
+  color?: string; // Custom color for track visualization (hex or CSS color)
 }
 ```
 
+### JavaScript API
+
+Control the player programmatically:
+
+```javascript
+const waveRoll = document.querySelector('wave-roll');
+
+// Playback controls
+await waveRoll.play();
+waveRoll.pause();
+waveRoll.seek(30);  // Seek to 30 seconds
+
+// State
+console.log(waveRoll.isPlaying);  // boolean
+console.log(waveRoll.getState()); // { currentTime, duration, tempo, ... }
+```
+
+### Tempo Control
+
+WaveRoll includes an interactive tempo control with popover input:
+
+- Click the BPM badge in the player controls to adjust tempo
+- Supports a wide range of tempo adjustments
+- Audio playback automatically adjusts with pitch preservation
+
+### MIDI Export
+
+Export MIDI files with modified tempo via the Settings panel:
+
+1. Adjust tempo using the tempo control
+2. Open Settings (gear icon)
+3. Click "Export with Current Tempo"
+
+The exported file preserves all note data with updated tempo metadata.
+
+**Programmatic usage:**
+
+```javascript
+import { exportMidiWithTempo } from 'wave-roll';
+
+// Export MIDI with new tempo (triggers download)
+await exportMidiWithTempo(midiFile, 144);
+
+// Export as Blob for custom handling
+import { exportMidiWithTempoAsBlob } from 'wave-roll';
+const blob = await exportMidiWithTempoAsBlob(midiFile, 144);
+```
+
 ## Development
 
 ```bash
 # Install dependencies
-npm install
+pnpm install
 
 # Run development server
-npm run dev
+pnpm dev
 
 # Build for production
-npm run build
+pnpm build
 
 # Run tests
-npm test
+pnpm test
 ```
 
 ## Acknowledgments
@@ -237,5 +299,10 @@ MIT License - see [LICENSE](LICENSE) file for details
 If you use WaveRoll in your research, please cite:
 
 ```bibtex
-
+@inproceedings{waveroll2025,
+  title={WaveRoll: JavaScript Library for Comparative MIDI Piano-Roll Visualization},
+  author={Park, Hannah and Jeong, Dasaem},
+  booktitle={Proceedings of 26th International Society for Music Information Retrieval Conference (ISMIR)},
+  year={2025}
+}
 ```

index.html

@@ -48,17 +48,24 @@
   <body>
     <div id="app">
       <header>
-        <h1><a href="https://www.github.com/crescent-stdio/wave-roll" target="_blank" rel="noopener">WaveRoll - MIDI Visualizer</a></h1>
+        <h1>
+          <a
+            href="https://www.github.com/crescent-stdio/wave-roll"
+            target="_blank"
+            rel="noopener"
+            >WaveRoll - MIDI Visualizer</a
+          >
+        </h1>
       </header>
       <wave-roll
         style="height: calc(100vh - 100px); display: block; width: 100%"
         files='[
-            {"path": "./src/sample_midi/chopin_audio.mp3", "name": "Chopin Etude Op. 10 No. 12", "type": "audio"},
-            {"path": "./src/sample_midi/chopin_ground_truth.midi", "name": "Ground Truth", "type": "midi"},
-            {"path": "./src/sample_midi/chopin_model_y.midi", "name": "Model Y Output", "type": "midi"},
-            {"path": "./src/sample_midi/chopin_model_b.midi", "name": "Model B Output", "type": "midi"}
+        {"path": "./src/sample_midi/chopin_audio.mp3", "name": "Chopin Etude Op. 10 No. 12", "type": "audio"},
+          {"path": "./src/sample_midi/chopin_ground_truth.midi", "name": "Ground Truth", "type": "midi"},
+          {"path": "./src/sample_midi/chopin_model_y.midi", "name": "Model Y Output", "type": "midi"},
+          {"path": "./src/sample_midi/chopin_model_b.midi", "name": "Model B Output", "type": "midi"}
         ]'
-        ></wave-roll>
+      ></wave-roll>
 
       <script type="module">
         import "/src/index.ts";

package.json

@@ -1,6 +1,6 @@
 {
   "name": "wave-roll",
-  "version": "0.2.5",
+  "version": "0.3.0",
   "description": "JavaScript Library for Comparative MIDI Piano-Roll Visualization",
   "main": "dist/wave-roll.umd.js",
   "module": "dist/wave-roll.es.js",
@@ -39,7 +39,7 @@
   "author": "Hannah Park",
   "license": "MIT",
   "type": "module",
-  "sideEffects": false,
+  "sideEffects": true,
   "bugs": {
     "url": "https://github.com/crescent-stdio/wave-roll/issues"
   },
@@ -48,7 +48,7 @@
     "@types/node": "^24.0.3",
     "jsdom": "^27.0.0",
     "typescript": "^5.8.3",
-    "vite": "^7.0.0",
+    "vite": "^7.2.6",
     "vitest": "^2.1.9"
   },
   "dependencies": {