-- Copyright 2013 Evan Laforge -- This program is distributed under the terms of the GNU General Public -- License 3.0, see COPYING or http://www.gnu.org/licenses/gpl-3.0.txt {-# LANGUAGE CPP #-} {- | Functions to manipulate pitches in scales according to the rules of standard western music theory. Pitches are represented as 'Pitch.Pitch'es and 'Pitch.Degree's. They're generalized to work with any number of 'Pitch.PitchClass'es, but since each scale carries an implied key 'Layout' it can only handle pitch classes in a certain range. Internally there are no checks that the pitch class is in range, so the range has to be checked on parse or show. Parsing and showing is handled in "Derive.Scale.TheoryFormat". @ db eb fb gb ab bb cb c# d# e# f# g# a# b# c d e f g a b c | | | | | | | | | | | | | @ -} module Derive.Scale.Theory ( -- * constants piano_intervals, piano_layout, diatonic_layout -- * NoteNumber diatonic transposition , diatonic_to_chromatic -- * symbolic transposition , transpose_diatonic, transpose_chromatic -- * input , enharmonics_of , pitch_to_semis, degree_to_semis , semis_to_pitch, pick_enharmonic, semis_to_pitch_sharps , semis_to_nn, fsemis_to_nn, nn_to_semis -- ** key , Key(key_tonic, key_name, key_intervals, key_signature, key_layout), key , accidentals_at_pc , Signature, Intervals , layout , layout_pc_per_octave, layout_semis_per_octave , contains_degree #ifndef TESTING , Layout(layout_intervals) #else , Layout(..) , calculate_signature, step_of #endif ) where import qualified Data.List as List import qualified Data.Maybe as Maybe import qualified Data.Vector as Boxed import qualified Data.Vector.Unboxed as Vector import qualified Util.Num as Num import qualified Util.Pretty as Pretty import qualified Util.Seq as Seq import qualified Util.Vector as Vector import qualified Perform.Pitch as Pitch import Global -- * constants piano_intervals :: [Pitch.Semi] piano_intervals = [2, 2, 1, 2, 2, 2, 1] -- | The layout of keys on everyone's favorite boxed harp. piano_layout :: Layout piano_layout = layout piano_intervals diatonic_layout :: Pitch.PitchClass -> Layout diatonic_layout per_oct = layout $ replicate per_oct 1 -- * NoteNumber diatonic transposition -- | Convert a fractional number of diatonic steps to chromatic steps. diatonic_to_chromatic :: Key -> Pitch.Degree -> Double -> Double diatonic_to_chromatic key degree steps | steps == 0 = 0 | steps > 0 = Num.scale (transpose isteps) (transpose (isteps+1)) frac | otherwise = Num.scale (transpose (isteps-1)) (transpose isteps) (1 - abs frac) where (isteps, frac) = properFraction steps transpose = fromIntegral . chromatic_steps key degree -- | Convert diatonic steps to chromatic steps. chromatic_steps :: Key -> Pitch.Degree -> Int -> Pitch.Semi chromatic_steps key degree steps = case table Vector.!? (middle + step + steps2) of Just val -> oct_semis + val - table Vector.! (middle + step) -- 'make_table' should build a table big enough that this can't happen. Nothing -> error $ "ran out of transpose table for " ++ show (middle, step, steps2) ++ ": " ++ show table where step = step_of key degree (octaves, steps2) = steps `divMod` key_steps_per_octave key oct_semis = if octaves == 0 then 0 else octaves * layout_semis_per_octave (key_layout key) middle = Vector.length table `div` 2 table = key_transpose_table key -- * symbolic transposition -- | Transpose a pitch diatonically. If the key is diatonic (i.e. there is -- a 1:1 relationship between note letters and scale degrees), then this will -- increment or decrement the note letters by the number of steps and adjust -- the accidentals based on the key signature. Otherwise (i.e. for scales like -- whole-tone or octatonic), it will figure out the number of chromatic steps -- to transpose and act like 'transpose_chromatic'. transpose_diatonic :: Key -> Step -> Pitch.Pitch -> Pitch.Pitch transpose_diatonic key steps pitch@(Pitch.Pitch oct degree@(Pitch.Degree pc accs)) | steps == 0 = pitch | otherwise = case key_signature key of Just _ -> Pitch.Pitch (oct + oct2) $ Pitch.Degree pc2 $ accs - accidentals_at_pc key pc + accidentals_at_pc key pc2 Nothing -> transpose_chromatic key (chromatic_steps key degree steps) pitch where (oct2, pc2) = (pc + steps) `divMod` key_steps_per_octave key -- | Chromatic transposition. Try to pick a spelling that makes sense for the -- given key. transpose_chromatic :: Key -> Pitch.Semi -> Pitch.Pitch -> Pitch.Pitch transpose_chromatic key steps pitch | steps == 0 = pitch | otherwise = semis_to_pitch key $ pitch_to_semis layout pitch + steps where layout = key_layout key pitch_to_semis :: Layout -> Pitch.Pitch -> Pitch.Semi pitch_to_semis layout (Pitch.Pitch oct note) = oct * layout_semis_per_octave layout + degree_to_semis layout note degree_to_semis :: Layout -> Pitch.Degree -> Pitch.Semi degree_to_semis layout (Pitch.Degree pc_ accs) = Vector.sum (Vector.take pc (layout_intervals layout)) + accs + oct * layout_semis_per_octave layout where (oct, pc) = pc_ `divMod` layout_pc_per_octave layout -- | Pick the most sensible enharmonic for the given pitch. -- -- TODO I reduce to semis and then pick an enharmonic, so 5b# becomes 6c. But -- if they asked for 5b# they should get it. pick_enharmonic :: Key -> Pitch.Pitch -> Pitch.Pitch pick_enharmonic key = semis_to_pitch key . pitch_to_semis (key_layout key) -- | Convert an absolute semitones value to a pitch. This is a bit -- complicated because it wants to find the best spelling for the given key. semis_to_pitch :: Key -> Pitch.Semi -> Pitch.Pitch semis_to_pitch key semis = mkpitch $ case key_signature key of Just sig -> case List.find (in_scale sig) enharmonics of Nothing -> pick_enharmonic (sharp_signature sig) enharmonics Just note -> note Nothing -> pick_enharmonic (sharp_tonic key) enharmonics where mkpitch (oct, note) = Pitch.Pitch (octave + oct) note -- The (Pitch.Degree (-1) 0) error value is icky, but here's why it should -- never happen: It happens when enharmonics is empty. Since the values of -- layout_enharmonics are never [] as per the definition of 'layout', it -- means the mod of semis is out of range for the array, which means the -- sum of the intervals is larger than the length of layout_enharmonics. -- That shouldn't happen because layout_enharmonics is initialized to -- [.. | i <- intervals, a <- [0..i-1]]. pick_enharmonic use_sharps notes = fromMaybe (0, Pitch.Degree (-1) 0) $ Seq.minimum_on (key . Pitch.degree_accidentals . snd) notes where key accs = (if use_sharps then accs < 0 else accs > 0, abs accs) in_scale sig (_, note) = sig Vector.!? step_of key note == Just (Pitch.degree_accidentals note) enharmonics = fromMaybe [] $ layout_enharmonics layout Boxed.!? steps (octave, steps) = semis `divMod` layout_semis_per_octave layout layout = key_layout key -- Sharpish looking key signatures favor sharps. sharp_signature sig = Vector.count (>0) sig >= Vector.count (<0) sig sharp_tonic = (>=0) . Pitch.degree_accidentals . key_tonic -- | Like 'semis_to_pitch', but only emits sharps, so it doesn't require a key. semis_to_pitch_sharps :: Layout -> Pitch.Semi -> Pitch.Pitch semis_to_pitch_sharps layout semis = Pitch.Pitch (octave + oct) degree where (octave, steps) = semis `divMod` layout_semis_per_octave layout (oct, degree) = head $ enharmonics Boxed.! steps enharmonics = layout_enharmonics layout -- | Convert Semis to integral NNs. This is only valid for 12TET, which is the -- only scale where Semis correspond directly to NNs. -- -- It doesn't return 'Pitch.NoteNumber' because these values are specifically -- integral. -- -- NOTE [middle-c] Middle C is 5 octaves above NN 0, but is conventially called -- 4c. Therefore, a 'Pitch' with octave 0 actually starts at NN 12 (in 12TET), -- and I have to add an octave when converting from NNs and subtract an octave -- when converting from NNs. -- -- Previously I considered the octave offset a part of formatting, and added -- an octave in 'TheoryFormat.p_octave' and subtracted an octave in -- 'TheoryFormat.show_octave'. But I was unsatisfied because it applied to -- all scales, and it seemed confusing to ask for a Pitch with octave 4 and get -- a note with octave 3. TODO maybe the add/subtract octave should just go in -- TheoryFormat.absolute_c? semis_to_nn :: Pitch.Semi -> Int semis_to_nn = (+12) fsemis_to_nn :: Pitch.FSemi -> Pitch.NoteNumber fsemis_to_nn = Pitch.NoteNumber . (+12) nn_to_semis :: Int -> Pitch.Semi nn_to_semis = subtract 12 -- * input -- | Enharmonics of a pitch. -- -- This choses the next highest enharmonic until it wraps around, so if you -- repeatedly pick the first one you'll cycle through them all. enharmonics_of :: Layout -> Pitch.Pitch -> [Pitch.Pitch] enharmonics_of layout pitch = [ Pitch.Pitch (Pitch.pitch_octave pitch + oct) n | (oct, n) <- get_enharmonics (layout_intervals layout) (Pitch.pitch_degree pitch) ] -- * step {- | A degree is one step of a scale. Unlike 'Pitch.PitchClass' it's relative to the tonic of the key, but also may have a different range. This is because some scales, such as whole-tone or octatonic, have fewer or more degrees than 7, even though the underlying notation system uses only 7 letters. This means that not every Degree will map to a PitchClass. Another approach is to change the number of PitchClasses, which would result in a--h for octatonic, but it would not admit easy modulation from an octatonic scale to a septatonic one. 'Key' has more documentation about the PitchClass and Step distinction. -} type Step = Int -- * Key {- | A Key is a scale along with a tonic Pitch. There's a distinction between \"diatonic\" and \"chromatic\" keys. It's not really standard terminology, but within this module I call scales with a 1:1 'Pitch.PitchClass' to 'Degree' mapping \"diatonic\", and the ones without \"chromatic\". That's because diatonic transposition for the former kind of scale is defined in terms of pitch classes, regardless of what accidentals the 'Pitch.Degree' may have, but the latter kind of scale must resort to chromatic transposition, losing the spelling of the original note. Ultimately there is a tension between diatonic and chromatic systems. -} data Key = Key { key_tonic :: !Pitch.Degree -- | This is the name of the key without reference to its tonic, e.g. -- \"dorian\" or \"major\". , key_name :: !Text -- | Semitones between each scale degree. This should have at least two -- octaves of intervals, as needed by 'chromatic_steps'. If this is a -- diatonic key, each interval is one pitch class. , key_intervals :: Intervals -- | Nothing for a chromatic key. , key_signature :: Maybe Signature -- | Table to speed up diatonic transposition, see 'make_table'. , key_transpose_table :: Intervals , key_layout :: Layout } deriving (Eq, Show) -- | Map from a Step to the number of sharps or flats at that Step. type Signature = Vector.Vector Pitch.Accidentals -- | Semitones between each scale degree. type Intervals = Vector.Vector Pitch.Semi -- | Make a Key given intervals and a layout. If the number of intervals are -- equal to the number of intervals in the layout, the scale is considered -- diatonic and will get a 'Signature'. key :: Pitch.Degree -> Text -> [Pitch.Semi] -> Layout -> Key key tonic name intervals layout = Key { key_tonic = tonic , key_name = name , key_intervals = ints , key_signature = generate_signature tonic layout ints , key_transpose_table = make_table intervals , key_layout = layout } where ints = Vector.fromList intervals -- | Precalculated transpositions so I can figure out a transposition with -- a single table lookup. This goes out to two octaves on either direction -- so I can start at any degree and go up to an octave of transposition. -- Everything past an octave is chopped off by divMod and transposed with -- multiplication. make_table :: [Pitch.Semi] -> Intervals make_table intervals = Vector.fromList $ reverse (drop 1 (make (-) (reverse intervals))) ++ make (+) intervals where make f = take (length intervals * 2) . scanl f 0 . cycle generate_signature :: Pitch.Degree -> Layout -> Intervals -> Maybe Signature generate_signature tonic layout intervals | Vector.length (layout_intervals layout) /= Vector.length intervals = Nothing | otherwise = Just $ calculate_signature tonic (layout_intervals layout) intervals calculate_signature :: Pitch.Degree -> Intervals -> Intervals -> Intervals calculate_signature (Pitch.Degree pc accs) layout intervals = Vector.take (Vector.length intervals) $ Vector.zipWith subtract (Vector.scanl (+) 0 (rotate pc layout)) (Vector.scanl (+) accs intervals) where rotate n xs = post <> pre where (pre, post) = Vector.splitAt n xs key_is_diatonic :: Key -> Bool key_is_diatonic = Maybe.isJust . key_signature instance Pretty Key where format key@(Key tonic name ints sig _table _layout) = Pretty.record title [ ("intervals", Pretty.format (Vector.take (key_steps_per_octave key) ints)) , ("signature", Pretty.format sig) ] where title = Pretty.text "Key" Pretty.<+> Pretty.format tonic Pretty.<+> Pretty.text name -- | The number of accidentals in the key signature at the given pitch class. accidentals_at_pc :: Key -> Pitch.PitchClass -> Pitch.Accidentals accidentals_at_pc key pc = fromMaybe 0 $ do sig <- key_signature key sig Vector.!? diatonic_step_of key pc -- | Number of degrees in an octave for this scale. -- -- This is different from the number of PCs per octave, because scales like -- octatonic or whole tone don't have a mapping from PCs to scale degrees. key_steps_per_octave :: Key -> Step key_steps_per_octave = Vector.length . key_intervals -- | Figure out the relative scale step of a note in the given key. step_of :: Key -> Pitch.Degree -> Step step_of key note | key_is_diatonic key = diatonic_step_of key (Pitch.degree_pc note) | otherwise = Vector.find_before semis (key_intervals key) where semis = degree_to_semis (key_layout key) note -- | Figure out the (relative) scale step of an absolute PitchClass in -- a diatonic key. In a diatonic key, the step and pitch class are relative -- and absolute versions of the same thing. diatonic_step_of :: Key -> Pitch.PitchClass -> Step diatonic_step_of key pc = (pc - Pitch.degree_pc (key_tonic key)) `mod` key_steps_per_octave key -- ** Layout -- | A Layout represents the configuration of white and black keys. data Layout = Layout { -- | Map PitchClass to the number of sharps above it. layout_intervals :: !Intervals -- | Map Pitch.Semis to the enharmonic Notes at that PitchClass. , layout_enharmonics :: !(Boxed.Vector [(Pitch.Octave, Pitch.Degree)]) } deriving (Eq, Show) layout_semis_per_octave :: Layout -> Pitch.Semi layout_semis_per_octave = Vector.sum . layout_intervals layout_pc_per_octave :: Layout -> Pitch.PitchClass layout_pc_per_octave = Vector.length . layout_intervals layout :: [Pitch.Semi] -> Layout layout intervals = Layout { layout_intervals = vec , layout_enharmonics = Boxed.fromList $ map (\n -> (0, n) : get_enharmonics vec n) notes } where vec = Vector.fromList intervals notes = [ Pitch.Degree pc accs | (pc, int) <- zip [0..] intervals, accs <- [0..int-1] ] -- | Enharmonics of a note, along with an octave offset if the enharmonic -- wrapped an octave boundary. -- -- This choses the next highest enharmonic until it wraps around, so if you -- repeatedly pick the first one you'll cycle through them all. get_enharmonics :: Intervals -> Pitch.Degree -> [(Pitch.Octave, Pitch.Degree)] get_enharmonics intervals (Pitch.Degree note_pc note_accs) = [ mknote intervals (note_pc + pc) (note_accs + accs) | (pc, accs) <- pcs, abs (note_accs + accs) < 3 ] where -- Find the distance in semitones from neighbor pcs. pcs = [ (1, -diffs [0]) , (2, -diffs [0, 1]) , (-2, diffs [-2, -1]) , (-1, diffs [-1]) ] diffs = Num.sum . map (layout_at intervals . (note_pc+)) mknote intervals pc accs = (oct, Pitch.Degree pc2 accs) where (oct, pc2) = pc `divMod` Vector.length intervals layout_at :: Intervals -> Pitch.PitchClass -> Pitch.Accidentals layout_at intervals pc = fromMaybe 0 $ intervals Vector.!? (pc `mod` Vector.length intervals) -- | True if the degree exists as its own key in the layout. -- -- For a relative scale, the Intervals should be from 'key_intervals', which -- considers that the tonic is shifted to PC 0. For an absolute scale, the -- keyboard never shifts, so use 'layout_intervals'. contains_degree :: Intervals -> Pitch.Degree -> Bool contains_degree intervals (Pitch.Degree pc acc) | acc >= 0 = acc < layout_at intervals pc | otherwise = layout_at intervals (pc - 1) + acc > 0