@summer_icicle/time-traveler 0.1.0

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2026 amanogaw01
+
+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

@@ -0,0 +1,320 @@
+# Time Traveler
+
+[![CI](https://github.com/amanogawa01/time-traveler/actions/workflows/ci.yml/badge.svg)](https://github.com/amanogawa01/time-traveler/actions/workflows/ci.yml)
+
+Turn your Git history into music.
+
+Time Traveler is a command-line tool that analyzes the history of a Git repository and transforms its development activity into a deterministic musical soundscape.
+
+Instead of generating music with AI or randomly assigning notes, Time Traveler maps real repository data — commits, code changes, file activity, timestamps, and development patterns — directly to musical properties.
+
+## Features
+
+- Analyze the history of any local Git repository
+- Convert repository activity into a musical profile
+- Generate melody, bass, and pad layers
+- Export the result as a stereo WAV file
+- Play generated soundscapes directly from the CLI
+- Analyze or export specific Git branches
+- Handle repositories ranging from a few commits to more than a million
+- Stream large Git histories without loading the entire raw Git log into memory
+- Adaptively aggregate enormous repositories while preserving their overall history
+- Produce deterministic output from repository data
+- No AI-generated music
+- No external audio libraries required for synthesis
+
+## How It Works
+
+Time Traveler reads Git history and maps development activity to musical characteristics.
+
+Repository-wide statistics influence the overall musical profile:
+
+| Git data | Musical property |
+| --- | --- |
+| Commits per day | Tempo |
+| Average lines changed | Intensity |
+| Deletion/churn ratio | Dissonance and scale |
+| Average files changed | Note density |
+| Busiest commit hour | Root note |
+| Code-change intensity | Waveform |
+
+Individual commits influence the composition:
+
+| Commit data | Musical property |
+| --- | --- |
+| Insertions and files changed | Scale degree |
+| Deletion ratio | Harmonic tension |
+| Files changed | Note duration |
+| Commit size | Amplitude |
+| Commit time | Octave |
+| Time between commits | Event spacing |
+
+Each musical commit produces five events:
+
+- 1 melody voice
+- 1 bass voice
+- 3 pad voices forming a chord
+
+The synthesizer then renders those events into stereo PCM audio and writes a WAV file.
+
+## Large Repositories
+
+Repositories with up to 1,000 commits are represented commit-by-commit.
+
+For larger histories, Time Traveler automatically groups neighboring commits into chronological buckets. Each bucket combines the activity of the commits it represents.
+
+This prevents extremely large repositories from producing millions of simultaneous music events while still representing the complete repository history.
+
+Time Traveler has been stress-tested against repositories including:
+
+- Linux kernel — more than 1.4 million commits processed
+- LLVM — more than 590,000 commits processed
+
+## Requirements
+
+- Node.js 20 or newer
+- Git
+
+## Installation
+
+Clone the repository:
+
+```bash
+git clone https://github.com/amanogawa01/time-traveler.git
+cd time-traveler
+```
+
+Install dependencies:
+
+```bash
+npm install
+```
+
+Build the project:
+
+```bash
+npm run build
+```
+
+Link the CLI globally:
+
+```bash
+npm link
+```
+
+You can then use `time-traveler` from inside any Git repository.
+
+## Usage
+
+### Analyze a repository
+
+Run:
+
+```bash
+time-traveler analyze
+```
+
+Example output:
+
+```text
+Time Traveler
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Repository
+  Branch: main
+  Commits: 18
+  Age: 5.1 days
+
+Code Activity
+  Lines added: 7,279
+  Lines deleted: 1,142
+  Total lines changed: 8,421
+  Files changed: 86
+  Churn ratio: 13.6%
+
+Commit Activity
+  Commits/day: 3.50
+  Avg lines/commit: 467.8
+  Busiest hour: 3:00 PM
+
+Musical Profile
+  Tempo: 85 BPM
+  Root note: G
+  Scale: major
+  Waveform: triangle
+  Intensity: 0.47
+  Dissonance: 0.14
+  Note density: 0.24
+```
+
+### Export a WAV file
+
+```bash
+time-traveler export
+```
+
+The default filename contains the repository name, branch, and latest commit hash:
+
+```text
+time-traveler-main-abcdef1.wav
+```
+
+Specify a custom filename with:
+
+```bash
+time-traveler export --output my-history.wav
+```
+
+or:
+
+```bash
+time-traveler export -o my-history.wav
+```
+
+### Play the repository
+
+```bash
+time-traveler play
+```
+
+Time Traveler generates the composition and opens it using the operating system's default audio player.
+
+### Use a specific branch
+
+All repository commands support a local branch with `--branch` or `-b`.
+
+```bash
+time-traveler analyze --branch develop
+```
+
+```bash
+time-traveler export --branch develop
+```
+
+```bash
+time-traveler play --branch develop
+```
+
+## Development
+
+Run the CLI directly from TypeScript:
+
+```bash
+npm run dev -- analyze
+```
+
+Type-check the project:
+
+```bash
+npm run typecheck
+```
+
+Run the test suite:
+
+```bash
+npm test
+```
+
+Build:
+
+```bash
+npm run build
+```
+
+## Testing
+
+Time Traveler includes unit and integration coverage for:
+
+- Git history parsing
+- Real temporary Git repositories
+- Repository and branch detection
+- Streaming Git history
+- Musical profile mapping
+- Layered composition
+- Large-history aggregation
+- Deterministic composition
+- WAV encoding and stereo PCM output
+
+The project is also manually stress-tested against very large real-world Git repositories.
+
+GitHub Actions automatically runs type checking, tests, and the production build on pushes and pull requests.
+
+## Architecture
+
+```text
+Git Repository
+      │
+      ▼
+GitRepository
+      │
+      ▼
+GitHistoryParser
+      │
+      ▼
+GitCommit[]
+      │
+      ├──────────────► GitHistoryAnalyzer
+      │                       │
+      │                       ▼
+      │                GitHistoryStats
+      │                       │
+      │                       ▼
+      │                  MusicMapper
+      │                       │
+      │                       ▼
+      │                  MusicProfile
+      │
+      ▼
+MusicComposer
+      │
+      ▼
+MusicEvent[]
+      │
+      ▼
+Synthesizer
+      │
+      ▼
+StereoBuffer
+      │
+      ▼
+WavEncoder
+      │
+      ▼
+WAV file
+```
+
+## Audio Engine
+
+Time Traveler implements its own lightweight synthesis pipeline.
+
+The generated soundscape uses:
+
+- melody, bass, and pad layers
+- ADSR envelopes
+- sine, triangle, square, and sawtooth waveforms
+- layer-specific timbre blending
+- low-pass filtering
+- stereo panning
+- equal-power stereo mixing
+- soft clipping
+- 44.1 kHz 16-bit stereo PCM WAV output
+
+## Philosophy
+
+Time Traveler is not intended to make Git history sound like a conventional song.
+
+The goal is to create an audible representation of how a repository developed.
+
+Two repositories with different development patterns should produce different musical profiles, while running Time Traveler repeatedly on the same history should produce the same composition.
+
+The repository itself is the score.
+
+## Contributing
+
+Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+Please also read the [Code of Conduct](CODE_OF_CONDUCT.md) and [Security Policy](SECURITY.md).
+
+## License
+
+Time Traveler is released under the MIT License. See [LICENSE](LICENSE).

package/dist/audio/AudioPlayer.d.ts

@@ -0,0 +1,4 @@
+export declare class AudioPlayer {
+    play(filePath: string): Promise<void>;
+    private playDetached;
+}

package/dist/audio/AudioPlayer.js

@@ -0,0 +1,28 @@
+import { spawn } from "node:child_process";
+import { platform } from "node:os";
+export class AudioPlayer {
+    async play(filePath) {
+        const currentPlatform = platform();
+        switch (currentPlatform) {
+            case "win32":
+                this.playDetached("explorer.exe", [filePath]);
+                return;
+            case "darwin":
+                this.playDetached("open", [filePath]);
+                return;
+            case "linux":
+                this.playDetached("xdg-open", [filePath]);
+                return;
+            default:
+                throw new Error(`Unsupported platform: ${currentPlatform}`);
+        }
+    }
+    playDetached(command, args) {
+        const player = spawn(command, args, {
+            detached: true,
+            stdio: "ignore"
+        });
+        player.unref();
+    }
+}
+//# sourceMappingURL=AudioPlayer.js.map

package/dist/audio/AudioPlayer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AudioPlayer.js","sourceRoot":"","sources":["../../src/audio/AudioPlayer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAEnC,MAAM,OAAO,WAAW;IACf,KAAK,CAAC,IAAI,CACf,QAAgB;QAEhB,MAAM,eAAe,GACnB,QAAQ,EAAE,CAAC;QAEb,QAAQ,eAAe,EAAE,CAAC;YACxB,KAAK,OAAO;gBACV,IAAI,CAAC,YAAY,CACf,cAAc,EACd,CAAC,QAAQ,CAAC,CACX,CAAC;gBACF,OAAO;YAET,KAAK,QAAQ;gBACX,IAAI,CAAC,YAAY,CACf,MAAM,EACN,CAAC,QAAQ,CAAC,CACX,CAAC;gBACF,OAAO;YAET,KAAK,OAAO;gBACV,IAAI,CAAC,YAAY,CACf,UAAU,EACV,CAAC,QAAQ,CAAC,CACX,CAAC;gBACF,OAAO;YAET;gBACE,MAAM,IAAI,KAAK,CACb,yBAAyB,eAAe,EAAE,CAC3C,CAAC;QACN,CAAC;IACH,CAAC;IAEO,YAAY,CAClB,OAAe,EACf,IAAc;QAEd,MAAM,MAAM,GACV,KAAK,CACH,OAAO,EACP,IAAI,EACJ;YACE,QAAQ,EAAE,IAAI;YACd,KAAK,EAAE,QAAQ;SAChB,CACF,CAAC;QAEJ,MAAM,CAAC,KAAK,EAAE,CAAC;IACjB,CAAC;CACF"}

package/dist/audio/Envelope.d.ts

@@ -0,0 +1,9 @@
+export interface EnvelopeSettings {
+    attack: number;
+    decay: number;
+    sustain: number;
+    release: number;
+}
+export declare class Envelope {
+    amplitude(time: number, duration: number, settings: EnvelopeSettings): number;
+}

package/dist/audio/Envelope.js

@@ -0,0 +1,29 @@
+export class Envelope {
+    amplitude(time, duration, settings) {
+        const { attack, decay, sustain, release } = settings;
+        if (time < 0) {
+            return 0;
+        }
+        if (time < attack) {
+            return time / attack;
+        }
+        if (time < attack + decay) {
+            const decayProgress = (time - attack) / decay;
+            return (1 -
+                decayProgress *
+                    (1 - sustain));
+        }
+        const releaseStart = Math.max(attack + decay, duration - release);
+        if (time < releaseStart) {
+            return sustain;
+        }
+        if (time < duration) {
+            const releaseProgress = (time - releaseStart) /
+                Math.max(duration - releaseStart, 0.0001);
+            return (sustain *
+                (1 - releaseProgress));
+        }
+        return 0;
+    }
+}
+//# sourceMappingURL=Envelope.js.map

package/dist/audio/Envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Envelope.js","sourceRoot":"","sources":["../../src/audio/Envelope.ts"],"names":[],"mappings":"AAOA,MAAM,OAAO,QAAQ;IACZ,SAAS,CACd,IAAY,EACZ,QAAgB,EAChB,QAA0B;QAE1B,MAAM,EACJ,MAAM,EACN,KAAK,EACL,OAAO,EACP,OAAO,EACR,GAAG,QAAQ,CAAC;QAEb,IAAI,IAAI,GAAG,CAAC,EAAE,CAAC;YACb,OAAO,CAAC,CAAC;QACX,CAAC;QAED,IAAI,IAAI,GAAG,MAAM,EAAE,CAAC;YAClB,OAAO,IAAI,GAAG,MAAM,CAAC;QACvB,CAAC;QAED,IAAI,IAAI,GAAG,MAAM,GAAG,KAAK,EAAE,CAAC;YAC1B,MAAM,aAAa,GACjB,CAAC,IAAI,GAAG,MAAM,CAAC,GAAG,KAAK,CAAC;YAE1B,OAAO,CACL,CAAC;gBACD,aAAa;oBACX,CAAC,CAAC,GAAG,OAAO,CAAC,CAChB,CAAC;QACJ,CAAC;QAED,MAAM,YAAY,GAChB,IAAI,CAAC,GAAG,CACN,MAAM,GAAG,KAAK,EACd,QAAQ,GAAG,OAAO,CACnB,CAAC;QAEJ,IAAI,IAAI,GAAG,YAAY,EAAE,CAAC;YACxB,OAAO,OAAO,CAAC;QACjB,CAAC;QAED,IAAI,IAAI,GAAG,QAAQ,EAAE,CAAC;YACpB,MAAM,eAAe,GACnB,CAAC,IAAI,GAAG,YAAY,CAAC;gBACrB,IAAI,CAAC,GAAG,CACN,QAAQ,GAAG,YAAY,EACvB,MAAM,CACP,CAAC;YAEJ,OAAO,CACL,OAAO;gBACP,CAAC,CAAC,GAAG,eAAe,CAAC,CACtB,CAAC;QACJ,CAAC;QAED,OAAO,CAAC,CAAC;IACX,CAAC;CACF"}

package/dist/audio/LowPassFilter.d.ts

@@ -0,0 +1,5 @@
+export declare class LowPassFilter {
+    private previousOutput;
+    process(input: number, cutoffFrequency: number, sampleRate: number): number;
+    reset(): void;
+}

package/dist/audio/LowPassFilter.js

@@ -0,0 +1,14 @@
+export class LowPassFilter {
+    previousOutput = 0;
+    process(input, cutoffFrequency, sampleRate) {
+        const deltaTime = 1 / sampleRate;
+        const rc = 1 / (2 * Math.PI * cutoffFrequency);
+        const alpha = deltaTime / (rc + deltaTime);
+        this.previousOutput = this.previousOutput + alpha * (input - this.previousOutput);
+        return this.previousOutput;
+    }
+    reset() {
+        this.previousOutput = 0;
+    }
+}
+//# sourceMappingURL=LowPassFilter.js.map

package/dist/audio/LowPassFilter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LowPassFilter.js","sourceRoot":"","sources":["../../src/audio/LowPassFilter.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,aAAa;IAChB,cAAc,GAAG,CAAC,CAAC;IACpB,OAAO,CAAE,KAAa,EAAE,eAAuB,EAAE,UAAkB;QACxE,MAAM,SAAS,GAAG,CAAC,GAAG,UAAU,CAAC;QACjC,MAAM,EAAE,GAAG,CAAC,GAAE,CAAC,CAAC,GAAG,IAAI,CAAC,EAAE,GAAG,eAAe,CAAC,CAAC;QAC9C,MAAM,KAAK,GAAG,SAAS,GAAG,CAAC,EAAE,GAAG,SAAS,CAAC,CAAC;QAC3C,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,cAAc,GAAG,KAAK,GAAG,CAAC,KAAK,GAAG,IAAI,CAAC,cAAc,CAAC,CAAC;QAClF,OAAO,IAAI,CAAC,cAAc,CAAC;IAC7B,CAAC;IACM,KAAK;QACV,IAAI,CAAC,cAAc,GAAG,CAAC,CAAC;IAC1B,CAAC;CACF"}

package/dist/audio/Oscillator.d.ts

@@ -0,0 +1,8 @@
+import type { Waveform } from "../music/MusicProfile.js";
+export declare class Oscillator {
+    sample(waveform: Waveform, frequency: number, time: number): number;
+    private sine;
+    private triangle;
+    private sawtooth;
+    private square;
+}

package/dist/audio/Oscillator.js

@@ -0,0 +1,42 @@
+export class Oscillator {
+    sample(waveform, frequency, time) {
+        switch (waveform) {
+            case "sine":
+                return this.sine(frequency, time);
+            case "triangle":
+                return this.triangle(frequency, time);
+            case "sawtooth":
+                return this.sawtooth(frequency, time);
+            case "square":
+                return this.square(frequency, time);
+        }
+    }
+    sine(frequency, time) {
+        return Math.sin(2 *
+            Math.PI *
+            frequency *
+            time);
+    }
+    triangle(frequency, time) {
+        return (2 /
+            Math.PI *
+            Math.asin(Math.sin(2 *
+                Math.PI *
+                frequency *
+                time)));
+    }
+    sawtooth(frequency, time) {
+        return (2 *
+            (frequency * time -
+                Math.floor(frequency * time + 0.5)));
+    }
+    square(frequency, time) {
+        return (Math.sin(2 *
+            Math.PI *
+            frequency *
+            time) >= 0
+            ? 1
+            : -1);
+    }
+}
+//# sourceMappingURL=Oscillator.js.map

package/dist/audio/Oscillator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Oscillator.js","sourceRoot":"","sources":["../../src/audio/Oscillator.ts"],"names":[],"mappings":"AAEA,MAAM,OAAO,UAAU;IACd,MAAM,CACX,QAAkB,EAClB,SAAiB,EACjB,IAAY;QAEZ,QAAQ,QAAQ,EAAE,CAAC;YACjB,KAAK,MAAM;gBACT,OAAO,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;YAEpC,KAAK,UAAU;gBACb,OAAO,IAAI,CAAC,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;YAExC,KAAK,UAAU;gBACb,OAAO,IAAI,CAAC,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;YAExC,KAAK,QAAQ;gBACX,OAAO,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;QACxC,CAAC;IACH,CAAC;IAEO,IAAI,CACV,SAAiB,EACjB,IAAY;QAEZ,OAAO,IAAI,CAAC,GAAG,CACb,CAAC;YACD,IAAI,CAAC,EAAE;YACP,SAAS;YACT,IAAI,CACL,CAAC;IACJ,CAAC;IAEO,QAAQ,CACd,SAAiB,EACjB,IAAY;QAEZ,OAAO,CACL,CAAC;YACC,IAAI,CAAC,EAAE;YACP,IAAI,CAAC,IAAI,CACP,IAAI,CAAC,GAAG,CACN,CAAC;gBACD,IAAI,CAAC,EAAE;gBACP,SAAS;gBACT,IAAI,CACL,CACF,CACJ,CAAC;IACJ,CAAC;IAEO,QAAQ,CACd,SAAiB,EACjB,IAAY;QAEZ,OAAO,CACL,CAAC;YACD,CACE,SAAS,GAAG,IAAI;gBAChB,IAAI,CAAC,KAAK,CACR,SAAS,GAAG,IAAI,GAAG,GAAG,CACvB,CACF,CACF,CAAC;IACJ,CAAC;IAEO,MAAM,CACZ,SAAiB,EACjB,IAAY;QAEZ,OAAO,CACL,IAAI,CAAC,GAAG,CACN,CAAC;YACD,IAAI,CAAC,EAAE;YACP,SAAS;YACT,IAAI,CACL,IAAI,CAAC;YACJ,CAAC,CAAC,CAAC;YACH,CAAC,CAAC,CAAC,CAAC,CACP,CAAC;IACJ,CAAC;CACF"}

package/dist/audio/StereoBuffer.d.ts

@@ -0,0 +1,4 @@
+export interface StereoBuffer {
+    left: Float32Array;
+    right: Float32Array;
+}

package/dist/audio/StereoBuffer.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=StereoBuffer.js.map

package/dist/audio/StereoBuffer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"StereoBuffer.js","sourceRoot":"","sources":["../../src/audio/StereoBuffer.ts"],"names":[],"mappings":""}

package/dist/audio/Synthesizer.d.ts

@@ -0,0 +1,21 @@
+import type { MusicEvent } from "../music/MusicEvent.js";
+import type { StereoBuffer } from "./StereoBuffer.js";
+export interface SynthesizerOptions {
+    sampleRate: number;
+}
+export declare class Synthesizer {
+    private readonly oscillator;
+    private readonly envelope;
+    render(events: MusicEvent[], options?: SynthesizerOptions): StereoBuffer;
+    private renderEvent;
+    private getTimbreSample;
+    private getPan;
+    private getMelodyPan;
+    private getPadPan;
+    private calculatePanGains;
+    private getCutoffFrequency;
+    private getEnvelopeForLayer;
+    private getLayerGain;
+    private applyMasterGain;
+    private softClip;
+}