readme-waves 1.0.0 → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TakalaWang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,8 +1,11 @@
 # readme-waves
 
+[![npm](https://img.shields.io/npm/v/readme-waves)](https://www.npmjs.com/package/readme-waves)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Generate animated music equalizer visualizations for GitHub profile READMEs. Built in Rust.
+**[Web App](https://readme-wave.takalawang.dev)** | **[npm](https://www.npmjs.com/package/readme-waves)**
+
+Generate animated music equalizer visualizations for GitHub profile READMEs.
 
 Renders your music as a contribution-graph-style equalizer — frequency bands from left (bass) to right (treble), with GitHub's green color levels stacking from bottom to top based on intensity.
 
@@ -17,30 +20,31 @@ Renders your music as a contribution-graph-style equalizer — frequency bands f
 
 ### CLI
 
-Requires [Rust](https://rustup.rs/) and [yt-dlp](https://github.com/yt-dlp/yt-dlp) (for YouTube mode).
+Requires [ffmpeg](https://ffmpeg.org/) and [yt-dlp](https://github.com/yt-dlp/yt-dlp) (for YouTube mode).
 
 ```bash
-# Build
-cargo build --release
-
-# From local audio file → SVG
-./target/release/readme-waves song.mp3 -o waveform.svg
+# From local audio file
+npx readme-waves song.mp3 -o waveform.svg
 
-# From local audio file → MP4 video with audio
-./target/release/readme-waves song.mp3 --video -o waveform.mp4
+# MP4 video with audio
+npx readme-waves song.mp3 --video -o waveform.mp4
 
-# From YouTube playlist (picks a random song)
-./target/release/readme-waves "https://www.youtube.com/playlist?list=PLxxxxx" -o waveform.svg
+# From YouTube URL
+npx readme-waves "https://www.youtube.com/watch?v=xxxxx" -o waveform.svg
 
-# Video from YouTube playlist
-./target/release/readme-waves "https://www.youtube.com/playlist?list=PLxxxxx" --video -o waveform.mp4
+# YouTube → MP4
+npx readme-waves "https://www.youtube.com/watch?v=xxxxx" --video -o waveform.mp4
 ```
 
+### Web App
+
+Visit **[readme-wave.takalawang.dev](https://readme-wave.takalawang.dev)** — upload an audio file to generate SVG or MP4 directly in your browser. No server processing, everything runs client-side.
+
 ### CLI Options
 
 | Flag | Description | Default |
 |------|-------------|---------|
-| `<input>` | Audio file path or YouTube playlist URL | (required) |
+| `<input>` | Audio file path or YouTube URL | (required) |
 | `-o, --output` | Output file path | `waveform.svg` |
 | `--video` | Generate MP4 video with audio | `false` |
 | `--rows` | Amplitude levels (height in squares) | `7` |
@@ -49,90 +53,51 @@ cargo build --release
 | `--fps` | Video frame rate | `24` |
 | `--duration` | SVG animation loop (seconds) | `10` |
 | `--theme` | Color theme: `dark`, `light` | `dark` |
-| `--background` | Background color | `transparent` |
-
-### GitHub Action
-
-> **Note:** The action currently generates SVG files. For video mode, use the CLI locally.
-
-Add to `.github/workflows/waveform.yml`:
-
-```yaml
-name: Generate Waveform
-
-on:
-  schedule:
-    - cron: '0 0 * * *'
-  workflow_dispatch:
-
-jobs:
-  generate:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
 
-      - uses: TakalaWang/readme-waves@main
-        with:
-          playlist_url: 'https://www.youtube.com/playlist?list=YOUR_PLAYLIST_ID'
-          output_path: assets/waveform.svg
-          rows: '7'
-          cols: '52'
-
-      - uses: stefanzweifel/git-auto-commit-action@v5
-        with:
-          commit_message: 'chore: update waveform'
-          file_pattern: 'assets/*'
-```
-
-Embed in your README:
+## Embed in GitHub README
 
 ```markdown
 ![Waveform](./assets/waveform.svg)
 ```
 
-### Action Inputs
-
-| Input | Description | Default |
-|-------|-------------|---------|
-| `audio_file` | Local audio file path | - |
-| `playlist_url` | YouTube playlist URL (random song daily) | - |
-| `output_path` | Output SVG path | `assets/waveform.svg` |
-| `rows` | Amplitude levels (grid height) | `7` |
-| `cols` | Frequency bands (grid width) | `52` |
-| `frames` | Animation frames | `60` |
-| `animation_duration` | Animation loop (seconds) | `10` |
-| `theme` | Color theme (`dark` or `light`) | `dark` |
-| `background_color` | SVG background | `transparent` |
-
 ## How It Works
 
-1. Decodes audio using [symphonia](https://github.com/pdeljanov/Symphonia) (pure Rust, no ffmpeg)
-2. Applies Short-Time Fourier Transform (STFT) via [rustfft](https://github.com/ejmahler/RustFFT)
+1. Decodes audio via ffmpeg (CLI) or Web Audio API (browser)
+2. Applies Short-Time Fourier Transform (STFT) with pure TypeScript FFT
 3. Trims to the lower 30% of the frequency range (where music energy lives)
 4. Per-band normalization with gamma correction for even dynamic range
 5. Generates equalizer visualization:
    - **SVG mode**: per-cell CSS `@keyframes` animation
-   - **Video mode**: raw pixel frames piped to ffmpeg with the original audio
+   - **Video mode**: raw pixel frames piped to ffmpeg (CLI) or ffmpeg.wasm (browser)
 
 ## Color Themes
 
 **Dark** (default) — GitHub dark mode contribution colors:
 ```
-#161b22  #0e4429  #006d32  #26a641  #39d353
+#161b22  #006d32  #26a641  #39d353
 ```
 
 **Light** — GitHub light mode contribution colors:
 ```
-#ebedf0  #9be9a8  #40c463  #30a14e  #216e39
+#ebedf0  #40c463  #30a14e  #216e39
+```
+
+## Local Development
+
+```bash
+pnpm install
+pnpm dev          # Next.js dev server
+pnpm build:cli    # Build CLI
 ```
 
 ## Tech Stack
 
-- [symphonia](https://github.com/pdeljanov/Symphonia) — pure Rust audio decoding (mp3, wav, flac, ogg, aac)
-- [rustfft](https://github.com/ejmahler/RustFFT) — FFT spectrum analysis
-- [clap](https://github.com/clap-rs/clap) — CLI argument parsing
-- [yt-dlp](https://github.com/yt-dlp/yt-dlp) — YouTube audio download (optional)
-- [ffmpeg](https://ffmpeg.org/) — video encoding (video mode only)
+- [Next.js](https://nextjs.org/) — web app
+- [Web Audio API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API) — browser audio decoding
+- [@ffmpeg/ffmpeg](https://github.com/ffmpegwasm/ffmpeg.wasm) — browser video encoding
+- [commander](https://github.com/tj/commander.js) — CLI
+- [yt-dlp](https://github.com/yt-dlp/yt-dlp) — YouTube download (CLI)
+- [ffmpeg](https://ffmpeg.org/) — audio/video processing (CLI)
 
 ## License
 

package/dist/cli/index.js

@@ -72,14 +72,14 @@ function logBands(bars, maxBin) {
   }
   return edges;
 }
-function extractSpectrumFromPCM(samples, _sampleRate, bars, frames) {
+function extractSpectrumFromPCM(samples, sampleRate, bars, frames, fps) {
   const totalSamples = samples.length;
-  const hopSize = Math.max(1, Math.floor((totalSamples - FFT_SIZE) / (frames - 1)));
+  const maxOffset = Math.max(0, totalSamples - FFT_SIZE);
   const halfBins = FFT_SIZE / 2;
   const edges = logBands(bars, halfBins);
   const raw = [];
   for (let f = 0; f < frames; f++) {
-    const offset = Math.min(f * hopSize, totalSamples - FFT_SIZE);
+    const offset = fps ? Math.min(Math.round(f * sampleRate / fps), maxOffset) : frames <= 1 ? 0 : Math.min(Math.round(f * maxOffset / (frames - 1)), maxOffset);
     const chunk = new Float64Array(FFT_SIZE);
     for (let i = 0; i < FFT_SIZE; i++) {
       chunk[i] = samples[offset + i] ?? 0;
@@ -110,11 +110,12 @@ function extractSpectrumFromPCM(samples, _sampleRate, bars, frames) {
   if (globalMax === 0) {
     return raw;
   }
+  const noiseFloor = globalMax * 0.03;
   const result = [];
   for (let f = 0; f < frames; f++) {
     const row = [];
     for (let b = 0; b < bars; b++) {
-      if (bandMax[b] === 0) {
+      if (bandMax[b] <= noiseFloor) {
         row.push(0);
         continue;
       }
@@ -126,7 +127,7 @@ function extractSpectrumFromPCM(samples, _sampleRate, bars, frames) {
   }
   return result;
 }
-async function extractSpectrumFromFile(filePath, bars, frames) {
+async function extractSpectrumFromFile(filePath, bars, frames, fps) {
   const { execFile: execFile2 } = await import("child_process");
   const { promisify: promisify2 } = await import("util");
   const exec2 = promisify2(execFile2);
@@ -141,7 +142,7 @@ async function extractSpectrumFromFile(filePath, bars, frames) {
     stdout.byteOffset,
     stdout.byteLength / 4
   );
-  return extractSpectrumFromPCM(samples, SAMPLE_RATE, bars, frames);
+  return extractSpectrumFromPCM(samples, SAMPLE_RATE, bars, frames, fps);
 }
 
 // lib/types.ts
@@ -275,32 +276,34 @@ async function downloadAudio(videoUrl, outputPath) {
 import { writeFile, mkdir, unlink } from "fs/promises";
 import { dirname, join } from "path";
 import { tmpdir } from "os";
-var program = new Command().name("readme-waves").description("Generate animated music equalizer SVGs").argument("<input>", "Audio file path or YouTube URL").option("-o, --output <path>", "Output path", "waveform.svg").option("--video", "Generate MP4 video with audio instead of SVG").option("--rows <n>", "Amplitude levels", "7").option("--cols <n>", "Frequency bands", "52").option("--frames <n>", "Animation frames (SVG mode)", "60").option("--fps <n>", "Video frame rate", "24").option("--duration <s>", "Animation duration in seconds (SVG mode)", "10").option("--theme <theme>", "Color theme: dark, light", "dark").action(async (input, opts) => {
+var program = new Command().name("readme-waves").description("Generate animated music equalizer SVGs").argument("<input>", "Audio file path or YouTube URL").option("-o, --output <path>", "Output path").option("-n, --name <name>", "Output filename (without extension)").option("--video", "Generate MP4 video with audio instead of SVG").option("--rows <n>", "Amplitude levels", "7").option("--cols <n>", "Frequency bands", "52").option("--frames <n>", "Animation frames (SVG mode)", "60").option("--fps <n>", "Video frame rate", "24").option("--duration <s>", "Animation duration in seconds (SVG mode)", "10").option("--theme <theme>", "Color theme: dark, light", "dark").action(async (input, opts) => {
   const isYoutube = input.includes("youtube.com") || input.includes("youtu.be");
   let audioPath = input;
-  let metadata;
+  let baseName = "waveform";
   let tempFile;
   if (isYoutube) {
     console.log("Fetching video info...");
     const info = await getVideoMetadata(input);
-    metadata = { title: info.title, artist: info.artist, url: info.url };
     console.log(`${info.title} - ${info.artist}`);
+    baseName = info.title.replace(/[/\\?%*:|"<>]/g, "-");
     tempFile = join(tmpdir(), `readme-waves-${info.id}.mp3`);
     console.log("Downloading audio...");
     await downloadAudio(input, tempFile);
     audioPath = tempFile;
   }
+  if (opts.name) baseName = opts.name;
+  const ext = opts.video ? ".mp4" : ".svg";
+  const outputPath = opts.output || `${baseName}${ext}`;
   if (opts.video) {
-    const { generateVideo, getAudioDuration } = await import("./video-7X5JNMOZ.js");
-    const output = opts.output.endsWith(".svg") ? opts.output.replace(".svg", ".mp4") : opts.output;
+    const { generateVideo, getAudioDuration } = await import("./video-ZMHOXSZH.js");
     const duration = await getAudioDuration(audioPath);
     const fps = +opts.fps;
     const totalFrames = Math.floor(duration * fps);
     console.log(`Audio: ${duration.toFixed(1)}s, generating ${totalFrames} frames...`);
-    const spectrum = await extractSpectrumFromFile(audioPath, +opts.cols, totalFrames);
-    await mkdir(dirname(output), { recursive: true });
-    await generateVideo(spectrum, audioPath, output, +opts.rows, +opts.cols, fps);
-    console.log(`Video saved to: ${output}`);
+    const spectrum = await extractSpectrumFromFile(audioPath, +opts.cols, totalFrames, fps);
+    await mkdir(dirname(outputPath), { recursive: true });
+    await generateVideo(spectrum, audioPath, outputPath, +opts.rows, +opts.cols, fps);
+    console.log(`Video saved to: ${outputPath}`);
   } else {
     console.log(`Extracting spectrum (${opts.cols} bands, ${opts.frames} frames)...`);
     const spectrum = await extractSpectrumFromFile(audioPath, +opts.cols, +opts.frames);
@@ -312,17 +315,11 @@ var program = new Command().name("readme-waves").description("Generate animated
         cols: +opts.cols,
         animationDuration: +opts.duration,
         theme: opts.theme
-      },
-      metadata
+      }
     );
-    await mkdir(dirname(opts.output), { recursive: true });
-    await writeFile(opts.output, svg);
-    console.log(`Saved to: ${opts.output}`);
-  }
-  if (metadata) {
-    const jsonPath = opts.output.replace(/\.(svg|mp4)$/, ".json");
-    await writeFile(jsonPath, JSON.stringify(metadata, null, 2));
-    console.log(`Metadata: ${jsonPath}`);
+    await mkdir(dirname(outputPath), { recursive: true });
+    await writeFile(outputPath, svg);
+    console.log(`Saved to: ${outputPath}`);
   }
   if (tempFile) await unlink(tempFile).catch(() => {
   });

package/dist/cli/{video-7X5JNMOZ.js → video-ZMHOXSZH.js}

@@ -16,9 +16,9 @@ var BG = [13, 17, 23];
 function rowColor(r, rows) {
   if (rows <= 1) return COLORS[3];
   const ratio = r / (rows - 1);
-  if (ratio < 0.33) return COLORS[1];
+  if (ratio < 0.33) return COLORS[3];
   if (ratio < 0.66) return COLORS[2];
-  return COLORS[3];
+  return COLORS[1];
 }
 async function generateVideo(spectrum, audioPath, outputPath, rows, cols, fps) {
   if (spectrum.length === 0 || spectrum[0].length === 0) {
@@ -68,8 +68,8 @@ async function generateVideo(spectrum, audioPath, outputPath, rows, cols, fps) {
   ]);
   const stdin = ffmpeg.stdin;
   const frameSize = width * height * 3;
-  const buf = Buffer.alloc(frameSize);
   for (let f = 0; f < totalFrames; f++) {
+    const buf = Buffer.alloc(frameSize);
     for (let i = 0; i < frameSize; i += 3) {
       buf[i] = BG[0];
       buf[i + 1] = BG[1];
@@ -97,19 +97,21 @@ async function generateVideo(spectrum, audioPath, outputPath, rows, cols, fps) {
         }
       }
     }
-    stdin.write(buf);
+    const ok = stdin.write(buf);
+    if (!ok) {
+      await new Promise((resolve) => stdin.once("drain", resolve));
+    }
     if (f % 100 === 0) {
       console.log(`  frame ${f + 1}/${totalFrames}`);
     }
   }
   await new Promise((resolve, reject) => {
-    stdin.end(() => {
-      ffmpeg.on("close", (code) => {
-        if (code === 0) resolve();
-        else reject(new Error(`ffmpeg exited with code ${code}`));
-      });
-      ffmpeg.on("error", reject);
+    ffmpeg.on("close", (code) => {
+      if (code === 0) resolve();
+      else reject(new Error(`ffmpeg exited with code ${code}`));
     });
+    ffmpeg.on("error", reject);
+    stdin.end();
   });
 }
 async function getAudioDuration(filePath) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "readme-waves",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Generate animated music equalizer SVGs for GitHub profile READMEs",
   "type": "module",
   "bin": {
@@ -25,9 +25,11 @@
   ],
   "author": "TakalaWang",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TakalaWang/readme-waves"
+  },
   "dependencies": {
-    "@ffmpeg/ffmpeg": "^0.12.15",
-    "@ffmpeg/util": "^0.12.2",
     "commander": "^14.0.3",
     "next": "^16.2.2",
     "react": "^19.2.4",