CMU Syllable Counter

A high-performance, production-ready JavaScript/TypeScript library for syllable counting and word hyphenation based on the CMU Pronouncing Dictionary with intelligent fallback algorithms.

Powered by: FreeSyllableCounter.com uses this cmu-syllable-counter package to power its syllable counting functionality. You can see the package in action by visiting their website!

🚀 Features

• CMU Dictionary Integration: Uses the Carnegie Mellon University Pronouncing Dictionary for accurate syllable counting
• Intelligent Fallback: Pattern-based algorithm for words not in the CMU dictionary
• Advanced Hyphenation: Customizable hyphenation with support for custom patterns and delimiters
• Word Analysis: Find words by syllable count, stress pattern, complexity, and vowel count
• Rhyming Detection: Find words that rhyme with any given word
• Random Word Generation: Get random words from the dictionary for testing
• Parallel Processing: Optimized for performance with parallel word processing
• TypeScript Support: Full TypeScript definitions and type safety
• Multiple Formats: Supports ESM, CommonJS, and UMD modules
• Comprehensive Testing: 100% test coverage with extensive test suite

🌟 Why This Library?

This library powers FreeSyllableCounter.com, which provides an excellent web interface for syllable counting. As developers, you can use the same powerful engine that drives their website in your own applications.

What makes this library special:

• Programmatic API: Use syllable counting in your Node.js, React, Vue, or any JavaScript application
• CMU Dictionary: More accurate than simple pattern-based algorithms
• Advanced Features: Beyond basic counting - includes hyphenation, word analysis, and rhyming
• Performance: Optimized for speed with parallel processing and caching
• TypeScript: Full type safety and IntelliSense support
• Flexible: Works with single words, sentences, or arrays of text

🔄 See It In Action

FreeSyllableCounter.com is powered by this very package! Visit their website to see the library in action and test its capabilities.

What you get with this package:

• Same Engine: The exact same syllable counting engine that powers FreeSyllableCounter.com
• Programmatic Access: Use it in your Node.js, React, Vue, or any JavaScript application
• Advanced Features: Beyond what's shown on the website - includes advanced word analysis, rhyming detection, and more
• Full Control: Customize hyphenation patterns, batch processing, and performance options
• TypeScript Support: Full type safety and IntelliSense support

When to use this library:

• Building applications that need syllable counting
• Processing large amounts of text
• Need programmatic access to syllable data
• Want advanced features like rhyming and word analysis
• Building poetry generators, language learning apps, or text analysis tools

When to use FreeSyllableCounter.com:

• Quick one-off syllable counting
• Learning about syllable counting
• Don't need programmatic access

📦 Installation

npm install cmu-syllable-counter

🎯 Quick Start

import { getSyllableCount, getHyphenatedString } from 'cmu-syllable-counter';

// Basic syllable counting
const result = await getSyllableCount('hello beautiful world');
console.log(result.totalSyllableCount); // 6

// With detailed analysis
const detailed = await getSyllableCount('hello beautiful world', {
  includeHyp: true,
  includePron: true,
  includeAnalysis: true
});
console.log(detailed);

// Get hyphenated string
const hyphenated = await getHyphenatedString('hello beautiful world');
console.log(hyphenated.hyp); // 'hel-lo beau-ti-ful world'

📚 API Reference

Core Functions

getSyllableCount(wordsOrSentences, options?)

The primary function for syllable counting and analysis.

Parameters:

• wordsOrSentences (string | string[]): A single word, sentence, or array of words/sentences
• options (SyllableCountOptions, optional): Configuration options

Options:

• includeHyp (boolean, default: false): Include word details with hyphenation
• delimiter (string, default: '-'): Custom delimiter for hyphenation
• includePron (boolean, default: false): Include CMU pronunciation data
• includeAnalysis (boolean, default: false): Include statistical analysis

Returns: Promise<SyllableCountResult>

Example:

const result = await getSyllableCount('algorithm programming', {
  includeHyp: true,
  delimiter: '·',
  includePron: true,
  includeAnalysis: true
});

console.log(result);
// {
//   totalSyllableCount: 7,
//   wordDetails: [
//     {
//       word: 'algorithm',
//       hyp: 'alg·ori·th·m',
//       sc: 4,
//       source: 'cmu',
//       pron: 'AE1 L G ER0 IH2 DH AH0 M'
//     },
//     {
//       word: 'programming',
//       hyp: 'progr·ammi·ng',
//       sc: 3,
//       source: 'cmu',
//       pron: 'P R OW1 G R AE2 M IH0 NG'
//     }
//   ],
//   analysis: {
//     totalWords: 2,
//     avgSyllablesPerWord: 3.5,
//     lines: 1
//   }
// }

getHyphenatedString(wordsOrSentences, options?)

Get hyphenated string with word details.

Parameters:

• wordsOrSentences (string | string[]): A single word, sentence, or array of words/sentences
• options (CoreHyphenationOptions, optional): Configuration options

Options:

• delimiter (string, default: '-'): Custom delimiter for hyphenation
• includeAnalysis (boolean, default: false): Include statistical analysis
• customPatterns (Record<string, string>): Custom hyphenation patterns

Returns: Promise<HyphenationResult>

Example:

const result = await getHyphenatedString('hello beautiful world', {
  delimiter: '·',
  includeAnalysis: true
});

console.log(result);
// {
//   hyp: 'hel·lo beau·ti·ful world',
//   words: [
//     { word: 'hello', hyp: 'hel·lo', sc: 2, source: 'cmu' },
//     { word: 'beautiful', hyp: 'beau·ti·ful', sc: 3, source: 'cmu' },
//     { word: 'world', hyp: 'world', sc: 1, source: 'cmu' }
//   ],
//   analysis: {
//     totalWords: 3,
//     avgSyllablesPerWord: 2,
//     lines: 1
//   }
// }

Dictionary Functions

cmuDictionary

The main dictionary instance for CMU lookups.

Methods:

• getWord(word): Get complete word data
• getPronunciation(word): Get CMU pronunciation
• getSyllableCount(word): Get syllable count
• getHyphenated(word): Get hyphenated version
• hasWord(word): Check if word exists
• getStats(): Get dictionary statistics
• getWords(words[]): Get multiple words at once
• isReady(): Check if dictionary is loaded

Example:

import { cmuDictionary } from 'cmu-syllable-counter';

// Get pronunciation
const pronunciation = await cmuDictionary.getPronunciation('hello');
console.log(pronunciation); // 'HH AH0 L OW1'

// Get syllable count
const syllableCount = await cmuDictionary.getSyllableCount('beautiful');
console.log(syllableCount); // 3

// Check if word exists
const exists = await cmuDictionary.hasWord('hello');
console.log(exists); // true

// Get dictionary stats
const stats = cmuDictionary.getStats();
console.log(stats); // { totalWords: 135158 }

findWordsBySyllableCount(syllableCount, options?)

Find words with a specific syllable count.

Parameters:

• syllableCount (number): Target syllable count
• options (WordSearchOptions, optional): Search options

Returns: WordAnalysis[]

Example:

import { findWordsBySyllableCount } from 'cmu-syllable-counter';

const words = findWordsBySyllableCount(2, { limit: 5 });
console.log(words);
// [
//   { word: 'hello', syllables: 2, pronunciation: 'HH AH0 L OW1' },
//   { word: 'world', syllables: 2, pronunciation: 'W ER1 L D' },
//   // ... more words
// ]

findWordsByStressPattern(pattern, options?)

Find words with a specific stress pattern.

Parameters:

• pattern (string): Stress pattern (e.g., '10', '01', '100')
• options (WordSearchOptions, optional): Search options

Returns: WordAnalysis[]

Example:

import { findWordsByStressPattern } from 'cmu-syllable-counter';

const words = findWordsByStressPattern('10', { limit: 3 });
console.log(words);
// [
//   { word: 'hello', stressPattern: '10', syllables: 2 },
//   // ... more words with stress pattern '10'
// ]

findWordsByComplexity(complexity, options?)

Find words by complexity level.

Parameters:

• complexity ('simple' | 'moderate' | 'complex'): Complexity level
• options (WordSearchOptions, optional): Search options

Returns: WordAnalysis[]

Example:

import { findWordsByComplexity } from 'cmu-syllable-counter';

const simpleWords = findWordsByComplexity('simple', { limit: 5 });
console.log(simpleWords);
// [
//   { word: 'cat', complexity: 'simple', syllables: 1 },
//   { word: 'dog', complexity: 'simple', syllables: 1 },
//   // ... more simple words
// ]

findWordsByVowelCount(vowelCount, options?)

Find words with a specific vowel count.

Parameters:

• vowelCount (number): Target vowel count
• options (WordSearchOptions, optional): Search options

Returns: WordAnalysis[]

Example:

import { findWordsByVowelCount } from 'cmu-syllable-counter';

const words = findWordsByVowelCount(2, { limit: 5 });
console.log(words);
// [
//   { word: 'hello', vowelCount: 2, consonantCount: 3 },
//   // ... more words with 2 vowels
// ]

getRandomWords(count?, options?)

Get random words from the dictionary.

Parameters:

• count (number, default: 10): Number of words to return
• options (WordSearchOptions, optional): Search options

Returns: WordAnalysis[]

Example:

import { getRandomWords } from 'cmu-syllable-counter';

const randomWords = getRandomWords(5, { 
  includePronunciation: true,
  includeSyllables: true 
});
console.log(randomWords);
// [
//   { word: 'random1', pronunciation: '...', syllables: 2 },
//   { word: 'random2', pronunciation: '...', syllables: 1 },
//   // ... 5 random words
// ]

findRhymingWords(targetWord, options?)

Find words that rhyme with the target word.

Parameters:

• targetWord (string): Word to find rhymes for
• options (WordSearchOptions, optional): Search options

Returns: WordAnalysis[]

Example:

import { findRhymingWords } from 'cmu-syllable-counter';

const rhymes = findRhymingWords('cat', { limit: 5 });
console.log(rhymes);
// [
//   { word: 'bat', pronunciation: 'B AE1 T', syllables: 1 },
//   { word: 'hat', pronunciation: 'HH AE1 T', syllables: 1 },
//   // ... more rhyming words
// ]

getAllWords()

Get all words in the dictionary.

Returns: string[]

Example:

import { getAllWords } from 'cmu-syllable-counter';

const allWords = getAllWords();
console.log(allWords.length); // 135158
console.log(allWords.slice(0, 5)); // ['a', 'aa', 'aaa', 'aachen', 'aaliyah']

getDictionarySize()

Get the total number of words in the dictionary.

Returns: number

Example:

import { getDictionarySize } from 'cmu-syllable-counter';

const size = getDictionarySize();
console.log(size); // 135158

isWordInDictionary(word)

Check if a word exists in the dictionary.

Parameters:

• word (string): Word to check

Returns: boolean

Example:

import { isWordInDictionary } from 'cmu-syllable-counter';

const exists = isWordInDictionary('hello');
console.log(exists); // true

const notExists = isWordInDictionary('xyzqwerty');
console.log(notExists); // false

CMU_DICTIONARY

Access the raw CMU dictionary data for custom utilities.

Type: Record<string, CMUDictionaryEntry>

Example:

import { CMU_DICTIONARY } from 'cmu-syllable-counter';

// Direct access to dictionary data
const helloData = CMU_DICTIONARY['hello'];
console.log(helloData);
// { s: 2, p: 'HH AH0 L OW1', h: 'hel-lo' }

// Build custom utilities
function getWordsBySyllableCount(targetSyllables) {
  return Object.entries(CMU_DICTIONARY)
    .filter(([word, data]) => data.s === targetSyllables)
    .map(([word, data]) => ({ word, ...data }));
}

const twoSyllableWords = getWordsBySyllableCount(2);
console.log(twoSyllableWords.slice(0, 3));
// [
//   { word: 'hello', s: 2, p: 'HH AH0 L OW1', h: 'hel-lo' },
//   { word: 'world', s: 2, p: 'W ER1 L D', h: 'world' },
//   // ... more words
// ]

🎨 TypeScript Types

Core Types

SyllableCountResult

interface SyllableCountResult {
  totalSyllableCount: number;
  wordDetails?: WordDetail[];
  analysis?: Analysis;
}

HyphenationResult

interface HyphenationResult {
  hyp: string;
  words: WordDetail[];
  analysis?: Analysis;
}

WordDetail

interface WordDetail {
  word: string;
  hyp: string;
  sc: number;
  source: "cmu" | "fallback";
  pron?: string;
}

Analysis

interface Analysis {
  totalWords: number;
  avgSyllablesPerWord: number;
  lines: number;
}

Option Types

SyllableCountOptions

interface SyllableCountOptions {
  includeHyp?: boolean;
  delimiter?: string;
  includePron?: boolean;
  includeAnalysis?: boolean;
}

CoreHyphenationOptions

interface CoreHyphenationOptions {
  delimiter?: string;
  includeAnalysis?: boolean;
  customPatterns?: Record<string, string>;
}

WordSearchOptions

interface WordSearchOptions {
  limit?: number;
  includePronunciation?: boolean;
  includeHyphenation?: boolean;
  includeSyllables?: boolean;
}

WordAnalysis

interface WordAnalysis {
  word: string;
  syllables?: number;
  pronunciation?: string;
  hyphenated?: string;
  phonemeCount?: number;
  vowelCount?: number;
  consonantCount?: number;
  stressPattern?: string;
  complexity?: 'simple' | 'moderate' | 'complex';
}

CMUDictionaryEntry

interface CMUDictionaryEntry {
  s: number;  // syllable count
  p: string;  // pronunciation (ARPAbet)
  h?: string; // hyphenation (optional)
}

CMUDictionary

type CMUDictionary = Record<string, CMUDictionaryEntry>;

🔧 Advanced Usage

Custom Hyphenation Patterns

const customPatterns = {
  'algorithm': 'al-go-rithm',
  'programming': 'pro-gram-ming',
  'development': 'de-vel-op-ment'
};

const result = await getHyphenatedString('algorithm programming', {
  customPatterns,
  delimiter: '·'
});
console.log(result.hyp); // 'al-go-rithm pro-gram-ming'

Processing Multiple Texts

const texts = [
  'hello world',
  'beautiful algorithm',
  'programming development'
];

const results = await Promise.all(
  texts.map(text => getSyllableCount(text, { includeAnalysis: true }))
);

results.forEach((result, index) => {
  console.log(`Text ${index + 1}: ${result.totalSyllableCount} syllables`);
});

Word Analysis and Search

// Find words by syllable count
const twoSyllableWords = findWordsBySyllableCount(2, { limit: 10 });

// Find rhyming words
const rhymes = findRhymingWords('cat', { limit: 5 });

// Get random words for testing
const randomWords = getRandomWords(10, { 
  includePronunciation: true,
  includeSyllables: true 
});

// Find words by complexity
const simpleWords = findWordsByComplexity('simple', { limit: 20 });

Custom Utilities with Raw Dictionary Data

import { CMU_DICTIONARY } from 'cmu-syllable-counter';

// Build custom word filters
function getWordsByStressPattern(pattern) {
  return Object.entries(CMU_DICTIONARY)
    .filter(([word, data]) => {
      const stresses = data.p.match(/\d+/g) || [];
      return stresses.join('') === pattern;
    })
    .map(([word, data]) => ({ word, ...data }));
}

// Find words with specific phoneme patterns
function getWordsWithPhoneme(phoneme) {
  return Object.entries(CMU_DICTIONARY)
    .filter(([word, data]) => data.p.includes(phoneme))
    .map(([word, data]) => ({ word, ...data }));
}

// Create custom syllable analysis
function analyzeSyllableDistribution() {
  const distribution = {};
  Object.values(CMU_DICTIONARY).forEach(entry => {
    distribution[entry.s] = (distribution[entry.s] || 0) + 1;
  });
  return distribution;
}

// Usage examples
const stressedWords = getWordsByStressPattern('10'); // First syllable stressed
const wordsWithK = getWordsWithPhoneme('K'); // Words containing 'K' sound
const syllableStats = analyzeSyllableDistribution(); // {1: 50000, 2: 40000, ...}

Performance Optimization

// The library automatically uses parallel processing for multiple words
// and includes LRU caching for repeated lookups

const longText = 'This is a very long text with many words...';
const result = await getSyllableCount(longText, {
  includeHyp: true,
  includeAnalysis: true
});

📊 Performance

• CMU Dictionary Lookups: ~0.1ms per word
• Fallback Algorithm: ~0.05ms per word
• Parallel Processing: Scales linearly with word count
• Caching: 1000-entry LRU cache for repeated words
• Memory Usage: Optimized for minimal memory footprint

🧪 Testing

The library includes comprehensive tests covering:

• Unit Tests: Individual function testing
• Integration Tests: End-to-end workflow testing
• Performance Tests: Load and stress testing
• Edge Cases: Empty strings, special characters, etc.

Run tests:

npm test

🏗️ Architecture

Core Components

1. CMU Dictionary Module: Handles pronunciation and syllable lookups
2. Fallback Algorithm: Pattern-based syllable counting
3. Hyphenation Engine: Knuth-Liang algorithm with custom patterns
4. Cache System: LRU cache for performance optimization
5. Parallel Processor: Concurrent word processing

Data Flow

Input → Word Extraction → CMU Lookup → Fallback (if needed) → Cache → Output

Optimization Features

• Pre-compiled Regex: Word extraction patterns
• Conditional Object Creation: Only include requested data
• Batch Processing: Parallel word processing
• Memory Management: Efficient data structures
• Tree Shaking: Dead code elimination

📈 Benchmarks

🔍 Debugging

Check dictionary statistics and word lookups:

// Check dictionary statistics
import { cmuDictionary, getDictionarySize } from 'cmu-syllable-counter';

const stats = cmuDictionary.getStats();
console.log('Dictionary stats:', stats);

const size = getDictionarySize();
console.log('Total words:', size);

// Check if specific words exist
const exists = await cmuDictionary.hasWord('hello');
console.log('Word exists:', exists);

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• CMU Pronouncing Dictionary: For accurate pronunciation data
• Knuth-Liang Algorithm: For hyphenation patterns
• Node.js Test Runner: For testing infrastructure

📞 Support

For issues, questions, or contributions, please visit the GitHub repository.

Built with ❤️ for accurate syllable counting and word analysis