🎼 A simple way to get a music pitch from a frequency.
Switch branches/tags
Nothing to show
Latest commit fed91a5 Oct 9, 2017
Type Name Latest commit message Commit time
Failed to load latest commit information.
Pitchy.xcodeproj Oct 9, 2017
Pitchy Dec 26, 2015
PitchyPlayground-iOS.playground Oct 9, 2017
PitchyTests Oct 9, 2017
Resources Jan 2, 2016
Source Oct 9, 2017
.gitignore Jan 3, 2016
.swift-version Oct 9, 2017
.travis.yml Oct 9, 2017
CONTRIBUTING.md Nov 8, 2015
Cartfile.private Oct 9, 2017
Cartfile.resolved Dec 26, 2015
Package.swift Jan 3, 2016
Pitchy.podspec Oct 9, 2017

Pitchy provides a simple way to get a music pitch from a frequency. Other than that it has a bunch of useful data structures, calculators and helper functions to work with notes, octaves and acoustic waves.

From Wikipedia:

Pitch is a perceptual property of sounds that allows their ordering on a frequency-related scale, or more commonly, pitch is the quality that makes it possible to judge sounds as "higher" and "lower" in the sense associated with musical melodies.

## Key features

• Get lower, higher and closest pitch offsets from a specified frequency.
• Get an acoustic wave with wavelength, period and harmonics.
• Create a note from a pitch index, frequency or a letter with octave number.
• Calculate a frequency, note letter and octave from a pitch index
• Find a pitch index from a specified frequency or a note letter with octave.
• Convert a frequency to wavelength and vice versa.
• Convert a wavelength to time period and vice versa.

## Usage

### Pitch

Create `Pitch` struct with a specified frequency to get lower, higher and closest pitch offsets:

```do {
// Frequency = 445 Hz
let pitch = try Pitch(frequency: 445.0)
let pitchOffsets = pitch.offsets

print(pitchOffsets.lower.frequency)     // 5 Hz
print(pitchOffsets.lower.percentage)    // 19.1%
print(pitchOffsets.lower.note.index)    // 0
print(pitchOffsets.lower.cents)         // 19.56

print(pitchOffsets.higher.frequency)    // -21.164 Hz
print(pitchOffsets.higher.percentage)   // -80.9%
print(pitchOffsets.higher.note.index)   // 1
print(pitchOffsets.higher.cents)        // -80.4338

print(pitchOffsets.closest.note.string) // "A4"

// You could also use acoustic wave
print(pitch.wave.wavelength)            // 0.7795 meters
} catch {
// Handle errors
}```

### Acoustic wave

Get an acoustic wave with wavelength, period and harmonics.

```do {
// AcousticWave(wavelength: 0.7795)
// AcousticWave(period: 0.00227259)
let wave = try AcousticWave(frequency: 440.0)

print(wave.frequency)       // 440 Hz
print(wave.wavelength)      // 0.7795 meters
print(wave.period)          // 0.00227259 s
print(wave.harmonics[0])    // 440 Hz
print(wave.harmonics[1])    // 880 Hz
} catch {
// Handle errors
}```

### Note

Note could be created with a corresponding frequency, letter + octave number or a pitch index.

```do {
// Note(frequency: 261.626)
// Note(letter: .C, octave: 4)
let note = try Note(index: -9)

print(note.index)                 // -9
print(note.letter)                // .C
print(note.octave)                // 4
print(note.frequency)             // 261.626 Hz
print(note.string)                // "C4"
print(try note.lower().string)    // "B3"
print(try note.higher().string)   // "C#4"
} catch {
// Handle errors
}```

### Calculators

Calculators are used in the initialization of `Pitch`, `AcousticWave` and `Note`, but also are included in the public API.

```do {
// PitchCalculator
let pitchOffsets = try PitchCalculator.offsets(445.0)
let cents = try PitchCalculator.cents(
frequency1: 440.0,
frequency2: 440.0
) // 19.56

// NoteCalculator
let frequency1 = try NoteCalculator.frequency(forIndex: 0)       // 440.0 Hz
let letter = try NoteCalculator.letter(forIndex: 0)              // .A
let octave = try NoteCalculator.octave(forIndex: 0)              // 4
let index1 = try NoteCalculator.index(forFrequency: 440.0)       // 0
let index2 = try NoteCalculator.index(forLetter: .A, octave: 4)  // 0

// WaveCalculator
let f = try WaveCalculator.frequency(forWavelength: 0.7795)      // 440.0 Hz
let wl1 = try WaveCalculator.wavelength(forFrequency: 440.0)     // 0.7795 meters
let wl2 = try WaveCalculator.wavelength(forPeriod: 0.00227259)   // 0.7795 meters
let period = try WaveCalculator.period(forWavelength: 0.7795)    // 0.00227259 s
} catch {
// Handle errors
}```

### FrequencyValidator

With a help of `FrequencyValidator` it's possible to adjust minimum and maximum frequencies that are used for validations in all calculations:

```FrequencyValidator.minimumFrequency = 20.0
FrequencyValidator.maximumFrequency = 4190.0```

### Error handling

Almost everything is covered with tests, but it's important to pass valid values, such as frequencies and pitch indexes. That's why there a re a list of errors that should be handled properly.

```enum Error: ErrorType {
case InvalidFrequency
case InvalidWavelength
case InvalidPeriod
case InvalidPitchIndex
case InvalidOctave
}```

## Installation

Pitchy is available through CocoaPods. To install it, simply add the following line to your Podfile:

`pod 'Pitchy'`

Pitchy is also available through Carthage. To install just write into your Cartfile:

`github "vadymmarkov/Pitchy"`