easy-imslp

A modern, type-safe TypeScript library for interacting with the IMSLP (International Music Score Library Project) API.

Features

• Type-safe: Full TypeScript support with detailed type definitions
• Lenient parsing: Returns partial data with warnings instead of throwing on parse errors
• Caching: Built-in in-memory caching with configurable TTL
• Rate limiting: Automatic rate limiting to respect IMSLP's API limits
• Async iterators: Efficient pagination for browsing large datasets
• Utility functions: Helpers for instrument normalization, catalogue parsing, and more

Installation

npm install easy-imslp

Requires Node.js 18+ (uses native fetch)

Quick Start

import { createClient } from 'easy-imslp';

const client = createClient();

// Search for pieces
const results = await client.search('moonlight sonata', {
  instrument: 'piano',
  limit: 10,
});

for (const work of results.data.items) {
  console.log(work.title);         // "Piano Sonata No.14"
  console.log(work.composer.name); // "Ludwig van Beethoven"
  console.log(work.opus);          // "Op.27 No.2"
}

// Handle parsing warnings
if (results.warnings.length > 0) {
  console.warn('Some data may be incomplete:', results.warnings);
}

API Reference

Creating a Client

import { createClient } from 'easy-imslp';

const client = createClient({
  cache: true,                    // Enable caching (default: true)
  cacheTTL: 5 * 60 * 1000,       // Cache TTL in ms (default: 5 minutes)
  timeout: 10000,                 // Request timeout in ms (default: 10000)
  userAgent: 'my-app/1.0',       // Custom user agent
  rateLimitDelay: 100,           // Delay between requests in ms (default: 100)
});

Search

// Search for works
const works = await client.search('beethoven symphony');

// Search with filters
const pianoWorks = await client.search('sonata', {
  instrument: 'piano',
  composer: 'Mozart',
  limit: 20,
});

// Search for composers
const composers = await client.searchComposers('Bach');

// Autocomplete (for search suggestions)
const suggestions = await client.autocomplete('beetho', 5);
// ["Beethoven, Ludwig van", "Beethoven's Wig", ...]

Getting Specific Items

// Get a composer by slug
const composer = await client.getComposer('Beethoven,_Ludwig_van');
console.log(composer.data.birthYear);  // 1770
console.log(composer.data.nationality); // "German"

// Get a work by exact slug
const work = await client.getWork('Piano_Sonata_No.14_(Beethoven,_Ludwig_van)');
console.log(work.data.key);            // "C-sharp minor"
console.log(work.data.year);           // 1801

// Fuzzy lookup (human-friendly input)
const result = await client.findWork('Moonlight Sonata Beethoven');
if (result.data) {
  console.log(result.data.title);
}

Browsing with Async Iterators

// Browse all works by a composer
for await (const result of client.browseComposerWorks('Bach,_Johann_Sebastian')) {
  console.log(result.data.title);

  // Can break early
  if (foundWhatWeNeed) break;
}

// Browse all composers
for await (const result of client.browseAllComposers()) {
  console.log(result.data.name);
}

Scores

// Get all scores for a work
const scores = await client.getWorkScores('Nocturnes_(Chopin,_Frederic)');

for (const score of scores.data) {
  console.log(score.filename);
  console.log(score.editor);
  console.log(score.isUrtext);
}

// Get download URL
const url = await client.getScoreDownloadUrl('PMLP01458-test.pdf');

Validation

const work = await client.getWork('...');

// Validate data quality
const validation = work.data.validate();
if (!validation.valid) {
  for (const issue of validation.issues) {
    console.warn(`${issue.field}: ${issue.message}`);
  }
}

Utility Functions

Import utilities separately for tree-shaking:

import {
  formatComposerName,
  normalizeInstrument,
  parseCatalogue,
  groupByInstrument,
} from 'easy-imslp/utils';

// Format composer names
formatComposerName('Beethoven,_Ludwig_van', 'full');   // "Ludwig van Beethoven"
formatComposerName('Beethoven,_Ludwig_van', 'short');  // "Beethoven"
formatComposerName('Beethoven,_Ludwig_van', 'sort');   // "Beethoven, Ludwig van"

// Normalize instrument names
normalizeInstrument('vln.');     // "violin"
normalizeInstrument('pf');       // "piano"
normalizeInstrument('violins');  // "violin"

// Parse catalogue numbers
parseCatalogue('BWV 1001');
// { raw: 'BWV 1001', system: 'bwv', number: 1001 }

parseCatalogue('Op. 27 No. 2');
// { raw: 'Op. 27 No. 2', system: 'op', number: 27, suffix: 'No.2' }

// Group works by instrument
const grouped = groupByInstrument(works);
// { piano: [...], violin: [...], orchestra: [...] }

Available Utilities

| Function | Description | |----------|-------------| | formatComposerName(slug, style) | Format composer slug as readable name | | normalizeInstrument(raw) | Normalize instrument abbreviations | | parseCatalogue(text) | Parse catalogue numbers (BWV, K, Op, etc.) | | groupByInstrument(works) | Group works by primary instrument | | groupByGenre(works) | Group works by genre | | groupByComposer(works) | Group works by composer | | buildDownloadUrl(filename) | Build IMSLP download URL | | parseYear(text) | Extract year from text |

Data Types

Work

interface Work {
  slug: string;
  title: string;              // "Piano Sonata No.14"
  fullTitle: string;          // "Piano Sonata No.14, Op.27 No.2"
  url: string;
  composer: ComposerReference;
  opus?: string;
  catalogue?: CatalogueInfo;
  key?: string;               // "C-sharp minor"
  year?: number;
  movements?: Movement[];
  instrumentation: InstrumentInfo[];
  genre?: string;
  difficulty?: DifficultyRating;
}

Composer

interface Composer {
  slug: string;
  name: string;               // "Ludwig van Beethoven"
  fullName: string;
  sortName: string;           // "Beethoven, Ludwig van"
  url: string;
  nationality?: string;
  birthYear?: number;
  deathYear?: number;
  timePeriod?: TimePeriod;
  worksCount?: number;
}

Score

interface Score {
  id: string;
  filename: string;
  url: string;
  downloadUrl: string;
  editor?: string;
  publisher?: string;
  publicationYear?: number;
  pageCount?: number;
  fileSize?: number;
  scanQuality?: 'low' | 'medium' | 'high';
  isUrtext?: boolean;
}

Error Handling

import { NotFoundError, NetworkError, isIMSLPError } from 'easy-imslp';

try {
  await client.getWork('NonExistent_Work');
} catch (error) {
  if (error instanceof NotFoundError) {
    console.error(error.message);
    console.error(error.details.url);
    console.error(error.details.suggestion);
  } else if (isIMSLPError(error)) {
    console.error(`IMSLP Error: ${error.code}`);
  }
}

Error Types

| Error | Description | |-------|-------------| | NotFoundError | Resource not found | | NetworkError | Network/connection issues | | RateLimitError | Rate limit exceeded | | ParseError | Failed to parse response | | TimeoutError | Request timed out |

Supported Catalogue Systems

The library recognizes these catalogue systems:

| System | Composer | Example | |--------|----------|---------| | BWV | Bach | BWV 1001 | | K / KV | Mozart | K. 331, KV 331 | | D | Schubert | D. 960 | | Op | General | Op. 27 No. 2 | | Hob | Haydn | Hob. XVI:52 | | HWV | Handel | HWV 56 | | RV | Vivaldi | RV 269 | | WoO | Beethoven | WoO 59 | | S | Liszt | S. 139 | | WWV | Wagner | WWV 86 | | TW | Telemann | TWV 51:D1 | | L | Debussy | L. 75 |

License

MIT

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

Acknowledgments

• IMSLP for providing free access to public domain sheet music
• The MediaWiki API for making this library possible