{"id":36540281,"url":"https://github.com/patrady/chord-js","last_synced_at":"2026-01-20T03:09:20.153Z","repository":{"id":58859658,"uuid":"530013380","full_name":"patrady/chord-js","owner":"patrady","description":"Recognizes all types of musical chords","archived":false,"fork":false,"pushed_at":"2023-08-12T21:59:50.000Z","size":159,"stargazers_count":13,"open_issues_count":2,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-11-23T12:02:59.415Z","etag":null,"topics":["chords","midi","music","music-theory","piano","typescript"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@patrady/chord-js","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/patrady.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-08-29T00:18:24.000Z","updated_at":"2025-10-14T01:14:29.000Z","dependencies_parsed_at":"2024-10-08T09:29:14.299Z","dependency_job_id":"d531348c-3322-474b-8c29-82372130be53","html_url":"https://github.com/patrady/chord-js","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/patrady/chord-js","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrady%2Fchord-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrady%2Fchord-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrady%2Fchord-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrady%2Fchord-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/patrady","download_url":"https://codeload.github.com/patrady/chord-js/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrady%2Fchord-js/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28335226,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-12T00:36:25.062Z","status":"online","status_checked_at":"2026-01-12T02:00:08.677Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chords","midi","music","music-theory","piano","typescript"],"created_at":"2026-01-12T05:45:02.433Z","updated_at":"2026-01-20T03:09:20.146Z","avatar_url":"https://github.com/patrady.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Chord JS\n\nChord JS is a music theory package that identifies notes, chords, and key signatures on an 88-key piano.\n\n## Quick Reference\n\n```ts\nimport { Note, Chord, KeySignature, KeySignatureOfD, Interval } from '@patrady/chord-js';\n\n// Create notes\nconst note = new Note('C#4');           // From string (note + accidental + octave)\nconst midi = Note.fromMidi(60);         // From MIDI value (60 = C4)\n\n// Identify chords\nChord.for('C E G')?.getName();          // \"C\" (C major)\nChord.for('A C E')?.getName();          // \"Am\" (A minor)\nChord.for([note1, note2, note3]);       // Also accepts Note array\n\n// Work with key signatures\nKeySignature.for('D')?.getNotes();      // D major scale notes\nnew KeySignatureOfD().normalize(new Note('Gb'));  // Returns F# (enharmonic)\nnew KeySignatureOfD().isInKey(new Note('F#'));    // true\n\n// Calculate intervals\nInterval.between(new Note('C4'), new Note('G4')).getSemitones();  // 7 (perfect 5th)\n```\n\n## Installation\n\nTo install run\n\n```bash\nnpm install @patrady/chord-js\n```\n\nor if you're using yarn\n\n```bash\nyarn add @patrady/chord-js\n```\n\n## Chords\n\nTo translate a series of notes into a chord, use\n\n```ts\nimport { Chord, Note } from '@patrady/chord-js';\n\n// From a space-separated string\nconst chord = Chord.for('C E G');\nchord?.getName(); // C\n\n// From an array of Note objects (useful for MIDI input)\nconst C = Note.fromMidi(60);\nconst E = Note.fromMidi(64);\nconst G = Note.fromMidi(67);\nChord.for([C, E, G])?.getName(); // C\n```\n\nThis table shows the type of supported chords with examples\n\n| Chord                                                                                          | Example                              |\n|------------------------------------------------------------------------------------------------|--------------------------------------|\n| [Major](https://en.wikipedia.org/wiki/Major_chord)                                             | `Chord.for(\"C E G\"); // C`           |\n| [Minor](https://en.wikipedia.org/wiki/Minor_chord)                                             | `Chord.for(\"C Eb G\"); // Cm`         |\n| [Suspended](https://en.wikipedia.org/wiki/Suspended_chord)                                     | `Chord.for(\"C F G\"); // Csus`        |\n| [Suspended Second](https://en.wikipedia.org/wiki/Suspended_chord)                              | `Chord.for(\"C D G\"); // Csus2`       |\n| [Augmented](https://en.wikipedia.org/wiki/Augmented_triad)                                     | `Chord.for(\"C E G#\"); // Caug`       |\n| [Diminished](https://en.wikipedia.org/wiki/Diminished_triad)                                   | `Chord.for(\"C Eb Gb\"); // Cdim`      |\n| [Inverted](https://en.wikipedia.org/wiki/Major_chord#Inversions)                               | `Chord.for(\"E G C\"); // C/E`         |\n| [Sixth](https://en.wikipedia.org/wiki/Sixth_chord)                                             | `Chord.for(\"C E G A\"); // C6`        |\n| [Minor Sixth](https://en.wikipedia.org/wiki/Sixth_chord)                                       | `Chord.for('C Eb G A'); // Cm6`      |\n| [Dominant Seventh](https://en.wikipedia.org/wiki/Dominant_seventh_chord)                       | `Chord.for(\"C E G Bb\"); // C7`       |\n| [Diminished Seventh](https://en.wikipedia.org/wiki/Diminished_seventh_chord)                   | `Chord.for(\"C Eb Gb A\"); // Cdim7`   |\n| [Augmented Seventh](https://en.wikipedia.org/wiki/Augmented_seventh_chord)                     | `Chord.for(\"C E G# Bb\"); // C+7`     |\n| [Major Seventh](https://en.wikipedia.org/wiki/Major_seventh_chord)                             | `Chord.for(\"C E G B\"); // Cmaj7`     |\n| [Augmented Major Seventh](https://en.wikipedia.org/wiki/Augmented_major_seventh_chord)         | `Chord.for(\"C E G# B\"); // Cmaj+7`   |\n| [Minor Seventh](https://en.wikipedia.org/wiki/Minor_seventh_chord)                             | `Chord.for(\"C Eb G Bb\"); // Cm7`     |\n| [Minor Major Seventh](https://en.wikipedia.org/wiki/Minor_major_seventh_chord)                 | `Chord.for(\"C Eb G B\"); // Cm7+`     |\n| [Half-Diminished Seventh](https://en.wikipedia.org/wiki/Half-diminished_seventh_chord)         | `Chord.for(\"C Eb Gb Bb\"); // Cø7`    |\n| [Seventh Suspended Fourth](https://en.wikipedia.org/wiki/Suspended_chord)                      | `Chord.for(\"C F G Bb\"); // C7sus4`   |\n| [Seventh Suspended Second](https://en.wikipedia.org/wiki/Suspended_chord)                      | `Chord.for(\"C D G Bb\"); // C7sus2`   |\n| [Add Ninth](https://en.wikipedia.org/wiki/Ninth_chord#Relation_to_other_chords_with_the_ninth) | `Chord.for(\"C E G D5\"); // Cadd9`    |\n| [Dominant Ninth](https://en.wikipedia.org/wiki/Ninth_chord#Dominant_ninth)                     | `Chord.for(\"C E G Bb D5\"); // C9`    |\n| [Dominant Minor Ninth](https://en.wikipedia.org/wiki/Ninth_chord#Dominant_minor_ninth)         | `Chord.for(\"C E G Bb Db5\"); // C7b9` |\n| [Minor Ninth](https://en.wikipedia.org/wiki/Ninth_chord#Minor_ninth)                           | `Chord.for(\"C Eb G Bb D5\"); // Cm9`  |\n| [Major Ninth](https://en.wikipedia.org/wiki/Ninth_chord#Major_ninth)                           | `Chord.for(\"C E G B D5\"); // Cmaj9`  |\n\n### Key Signatures\n\nA Key Signature is a combination of sharps and flats at the beginning of each stave.\n\nYou can create key signatures in two ways:\n\n```ts\n// Option 1: Using the factory method (dynamic)\nimport { KeySignature } from '@patrady/chord-js';\n\nconst key = KeySignature.for('D');\nkey?.getNotes();  // D, E, F#, G, A, B, C#, D\n\n// Option 2: Using the class directly\nimport { KeySignatureOfD } from '@patrady/chord-js';\n\nnew KeySignatureOfD().getNotes(); // D, E, F#, G, A, B, C#, D\n```\n\nKey signatures can normalize enharmonic notes and check membership:\n\n```ts\nimport { Note, KeySignatureOfD } from '@patrady/chord-js';\n\nnew KeySignatureOfD().normalize(new Note('Gb')); // F#\n\nnew KeySignatureOfD().isInKey(new Note('Gb')); // false\nnew KeySignatureOfD().isInKey(new Note('F#')); // true\n```\n\n| Attribute         | Description                                                            | Example                                                         |\n|-------------------|------------------------------------------------------------------------|-----------------------------------------------------------------|\n| `getNotes()`      | Returns an array of eight notes from the base to the octave.           | `new KeySignatureOfD().getNotes(); // D, E, F#, G, A, B, C#, D` |\n| `normalize(note)` | Normalizes a note from one key signature to the current key signature. | `new KeySignatureOfD().normalize(new Note(\"Gb\")); // F#`        |\n| `isInKey(note)`   | Returns whether a note is in the key signature                         | `new KeySignatureOfD().isInKey(new Note(\"Gb\")); // false`       |\n\n### Supported Key Signatures\n\nAll major key signatures are supported, including theoretical ones that use double sharps or double flats:\n\n| Key Signature | Name                   |\n|---------------|------------------------|\n| C             | `KeySignatureOfC`      |\n| Cb            | `KeySignatureOfCb`     |\n| C#            | `KeySignatureOfCSharp` |\n| D             | `KeySignatureOfD`      |\n| Db            | `KeySignatureOfDb`     |\n| D#            | `KeySignatureOfDSharp` |\n| E             | `KeySignatureOfE`      |\n| Eb            | `KeySignatureOfEb`     |\n| E#            | `KeySignatureOfESharp` |\n| F             | `KeySignatureOfF`      |\n| Fb            | `KeySignatureOfFb`     |\n| F#            | `KeySignatureOfFSharp` |\n| G             | `KeySignatureOfG`      |\n| Gb            | `KeySignatureOfGb`     |\n| G#            | `KeySignatureOfGSharp` |\n| A             | `KeySignatureOfA`      |\n| Ab            | `KeySignatureOfAb`     |\n| A#            | `KeySignatureOfASharp` |\n| B             | `KeySignatureOfB`      |\n| Bb            | `KeySignatureOfBb`     |\n| B#            | `KeySignatureOfBSharp` |\n\n## Notes\n\nA Note is the fundamental element of music. Notes are simply frequencies and are used to create [chords](#chords)\nand [key signatures](#key-signatures).\n\n```ts\nimport { Note } from '@patrady/chord-js';\n\nconst note = new Note('Eb4');\n```\n\n| Attribute             | Description                                                                                        | Example                             |\n|-----------------------|----------------------------------------------------------------------------------------------------|-------------------------------------|\n| `getName()`           | The name of the note and accidental                                                                | `note.getName(); // Eb`             |\n| `getScientificName()` | The name of the note, accidental, and octave                                                       | `note.getScientificName(); // Eb4`  |\n| `getOctave()`         | The octave between 0 and 8                                                                         | `note.getOctave(); // 4`            |\n| `getFrequency()`      | The frequency in Hz, up to 5 decimal places                                                        | `note.getFrequency(); // 311.12698` |\n| `getKeyNumber()`      | The [number](https://en.wikipedia.org/wiki/Piano_key_frequencies) of the key on an 88-key piano    | `note.getKeyNumber(); // 43`        |\n| `getMidiValue()`      | The [MIDI note](https://en.wikipedia.org/wiki/Piano_key_frequencies) of the key on an 88-key piano | `note.getMidiValue(); // 63`        |\n\n## MIDI Keyboard\n\nWhen interacting with a MIDI keyboard and you want to convert\na [MIDI value](https://www.inspiredacoustics.com/en/MIDI_note_numbers_and_center_frequencies) to a note, use\n\n```ts\nimport { Note } from '@patrady/chord-js';\n\nconst note = Note.fromMidi(24);\n\nnote.getScientificName(); // C1\n```\n\nFor [enharmonic](https://en.wikipedia.org/wiki/Enharmonic) notes, the MIDI value will be the same. For example, C# and\nDb in the 1st octave will have the same MIDI value of 25.\nTo choose a specific enharmonic, normalize the note to a key signature:\n\n```ts\nimport { Note, KeySignatureOfD, KeySignatureOfDb } from '@patrady/chord-js';\n\nconst note = Note.fromMidi(25);\n\nnew KeySignatureOfD().normalize(note); // C#\nnew KeySignatureOfDb().normalize(note); // Db\n```\n\n## Intervals\n\nCalculate the interval (distance in semitones) between two notes:\n\n```ts\nimport { Interval, Note } from '@patrady/chord-js';\n\n// Using strings\nconst interval = Interval.between('C4', 'G4');\ninterval.getSemitones();    // 7\ninterval.isPerfect5th();    // true\ninterval.isMajor3rd();      // false\n\n// Using Note objects\nconst c4 = new Note('C4');\nconst g4 = new Note('G4');\nInterval.between(c4, g4).isPerfect5th();  // true\n```\n\nThe `Interval` class also provides semitone constants:\n\n```ts\nInterval.isNone();      // 0 (unison)\nInterval.major2nd();    // 2\nInterval.major3rd();    // 4\nInterval.perfect4th();  // 5\nInterval.perfect5th();  // 7\nInterval.major6th();    // 9\nInterval.major7th();    // 11\nInterval.octave();      // 12\n```\n\n### Interval Check Methods\n\nThe `DefinedInterval` object (returned by `Interval.between()`) provides these check methods:\n\n| Method              | Semitones |\n|---------------------|-----------|\n| `isNone()`          | 0         |\n| `isMinor2nd()`      | 1         |\n| `isMajor2nd()`      | 2         |\n| `isMinor3rd()`      | 3         |\n| `isMajor3rd()`      | 4         |\n| `isDiminished4th()` | 4         |\n| `isPerfect4th()`    | 5         |\n| `isAugmented4th()`  | 6         |\n| `isDiminished5th()` | 6         |\n| `isPerfect5th()`    | 7         |\n| `isAugmented5th()`  | 8         |\n| `isMinor6th()`      | 8         |\n| `isMajor6th()`      | 9         |\n| `isDiminished7th()` | 9         |\n| `isMinor7th()`      | 10        |\n| `isMajor7th()`      | 11        |\n\n## Accidentals\n\nNotes support sharps, flats, double sharps, and double flats:\n\n```ts\nimport { Note } from '@patrady/chord-js';\n\nnew Note('C#4');   // C sharp\nnew Note('Db4');   // D flat\nnew Note('F𝄪4');   // F double sharp (enharmonic to G)\nnew Note('B𝄫4');   // B double flat (enharmonic to A)\n```\n\nNote: Double sharp uses the Unicode character `𝄪` (U+1D12A) and double flat uses `𝄫` (U+1D12B).\n\n## Note Comparison\n\nNotes can be compared for equality and ordering:\n\n```ts\nimport { Note } from '@patrady/chord-js';\n\nconst c4 = new Note('C4');\nconst db4 = new Note('Db4');\nconst cSharp4 = new Note('C#4');\n\n// Exact equality (same name, accidental, and octave)\nc4.equals(new Note('C4'));        // true\ncSharp4.equals(db4);              // false (different spelling)\n\n// Enharmonic equality (same pitch/MIDI value)\ncSharp4.matches(db4);             // true (same key on piano)\n\n// Ordering\nc4.isLessThan(db4);               // true\ndb4.isGreaterThan(c4);            // true\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpatrady%2Fchord-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpatrady%2Fchord-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpatrady%2Fchord-js/lists"}