Chordlock

API Reference

Chordlock provides multiple interfaces for different use cases.

Overview

Interface Use Case Performance Features
CLI Command-line usage, testing Native Full feature set
C++ Library Desktop applications Native Core engine
WebAssembly Web applications Near-native Browser compatibility
MCP Integration AI-powered analysis Network Claude integration

Core Concepts

Key Context

Chordlock’s key innovation is key-context aware chord detection:

// Set key context before analysis
detector.setKeyContext(0, false);  // C major
detector.setKeyContext(9, true);   // A minor

Key context affects:

Detection Modes

Chordlock offers multiple detection approaches:

// Basic detection
auto result = detector.detectChord();

// With alternatives
auto result = detector.detectChordWithAlternatives(5);

// With detailed analysis  
auto result = detector.detectChordWithDetailedAnalysis(10);

Roman Numeral Analysis

Automatic functional harmony analysis:

// Analyze current notes
auto degree = detector.analyzeCurrentNotesToDegree(tonic, isMinor);

// Analyze specific chord
auto degree = detector.analyzeDegree("Cmaj7", 0, false); // → "I7"

// Generate from degree
auto notes = detector.degreeToNotes("V7", 0, false); // → G7 notes

Common Workflows

1. Real-time MIDI Processing

class MIDIProcessor {
    Chordlock detector;
    
public:
    void setKey(int tonic, bool isMinor) {
        detector.setKeyContext(tonic, isMinor);
    }
    
    void onNoteOn(uint8_t note, uint8_t velocity) {
        detector.noteOn(note, velocity);
        
        auto result = detector.detectChord();
        if (result.hasValidChord) {
            auto degree = detector.analyzeCurrentNotesToDegree(tonic, isMinor);
            // Process result...
        }
    }
};

2. Batch Chord Analysis

std::vector<std::string> analyzeProgression(
    const std::vector<std::vector<int>>& chords,
    int tonic, bool isMinor) {
    
    Chordlock detector;
    detector.setKeyContext(tonic, isMinor);
    
    std::vector<std::string> results;
    for (const auto& chord : chords) {
        detector.clearAllNotes();
        for (int note : chord) {
            detector.noteOn(note, 80);
        }
        
        auto result = detector.detectChord();
        auto degree = detector.analyzeCurrentNotesToDegree(tonic, isMinor);
        results.push_back(result.chordName + " [" + degree + "]");
    }
    
    return results;
}

3. Chord Generation

// Generate chord progression
std::vector<std::string> degrees = {"I", "vi", "IV", "V"};
int tonic = 0; // C major

for (const auto& degree : degrees) {
    auto notes = detector.degreeToNotes(degree, tonic, false, 4);
    auto chordName = detector.degreeToChordName(degree, tonic, false);
    
    std::cout << degree << " = " << chordName << " = [";
    for (size_t i = 0; i < notes.size(); i++) {
        std::cout << notes[i];
        if (i < notes.size() - 1) std::cout << ", ";
    }
    std::cout << "]" << std::endl;
}

Error Handling

C++ Exceptions

try {
    auto result = detector.detectChord();
    if (!result.hasValidChord) {
        // Handle no chord detected
    }
} catch (const std::exception& e) {
    // Handle errors
}

CLI Error Codes

# Exit codes
0  # Success
1  # Invalid arguments
2  # File not found
3  # Invalid key specification
4  # No valid notes found

WebAssembly Error Handling

try {
    const result = Module.ccall('chordlock_detect_chord_detailed', 'string', ['number'], [5]);
    const data = JSON.parse(result);
    
    if (data.error) {
        console.error('Chordlock error:', data.error);
    }
} catch (e) {
    console.error('Module error:', e);
}

Performance Considerations

Optimization Tips

  1. Reuse instances: Create detector once, reuse for multiple analyses
  2. Batch operations: Group note changes when possible
  3. Limit alternatives: Only request needed number of alternatives
  4. Key context: Set once, analyze multiple chords in same key

Benchmarks

Operation C++ WebAssembly CLI
Single chord detection ~0.001ms ~0.002ms ~1ms
With 5 alternatives ~0.005ms ~0.010ms ~2ms
Roman numeral analysis ~0.001ms ~0.002ms ~0.5ms
Degree generation ~0.003ms ~0.005ms ~1ms

API Stability

Choose your interface and dive into the detailed documentation:

This site is open source. Improve this page.