music21/
tablature.rs

1//! Notes on the strings and frets of a fretted instrument: music21's
2//! `tablature`.
3//!
4//! ```
5//! use music21::tablature::{FretBoard, FretNote};
6//!
7//! let board = FretBoard::guitar(vec![FretNote::new(Some(1), Some(2), Some(2))], 4);
8//! let pitches = board.pitches()?;
9//! assert_eq!(pitches[5].as_ref().map(|pitch| pitch.name_with_octave()), Some("F#4".to_string()));
10//! # Ok::<(), music21::Error>(())
11//! ```
12
13use std::fmt;
14
15use crate::{
16    chordsymbol::ChordSymbol,
17    defaults::{FloatType, IntegerType},
18    error::{Error, Result},
19    pitch::{Pitch, microtone::ordinal_suffix},
20};
21
22/// A finger on a string at a fret: music21's `FretNote`. Strings count
23/// from the highest-sounding, one, as guitarists count them.
24#[derive(Clone, Debug, PartialEq, Eq)]
25#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
26pub struct FretNote {
27    /// The string.
28    pub string: Option<IntegerType>,
29    /// The fret, nought for the open string.
30    pub fret: Option<IntegerType>,
31    /// The finger.
32    pub fingering: Option<IntegerType>,
33    /// Whether the finger is shown: music21's `displayFingerNumber`.
34    pub display_finger_number: bool,
35}
36
37impl FretNote {
38    /// A note on a string at a fret, played by a finger, the finger shown.
39    pub fn new(
40        string: Option<IntegerType>,
41        fret: Option<IntegerType>,
42        fingering: Option<IntegerType>,
43    ) -> Self {
44        Self {
45            string,
46            fret,
47            fingering,
48            display_finger_number: true,
49        }
50    }
51}
52
53/// Written as music21 writes the note inside its representation: `6th
54/// string, 133rd fret, 2nd finger`, leaving out what is not given.
55impl fmt::Display for FretNote {
56    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
57        let parts: Vec<String> = [
58            (self.string, "string"),
59            (self.fret, "fret"),
60            (self.fingering, "finger"),
61        ]
62        .into_iter()
63        .filter_map(|(value, what)| {
64            value.map(|value| format!("{value}{} {what}", ordinal_suffix(value)))
65        })
66        .collect();
67        f.write_str(&parts.join(", "))
68    }
69}
70
71/// A fretted instrument's strings, the notes stopped on them, and their
72/// open pitches: music21's `FretBoard`.
73#[derive(Clone, Debug, PartialEq)]
74#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
75pub struct FretBoard {
76    /// How many strings there are.
77    pub strings: usize,
78    /// The notes stopped, in no particular order.
79    pub fret_notes: Vec<FretNote>,
80    /// How many frets a diagram shows.
81    pub display_frets: usize,
82    /// Each string's open pitch, lowest string first.
83    pub tuning: Vec<Pitch>,
84}
85
86fn tuned(names: &[&str]) -> Vec<Pitch> {
87    names
88        .iter()
89        .map(|name| Pitch::from_name(*name).expect("a tuning names pitches"))
90        .collect()
91}
92
93impl FretBoard {
94    /// A board of so many strings with these notes, not yet tuned.
95    pub fn new(strings: usize, fret_notes: Vec<FretNote>, display_frets: usize) -> Self {
96        Self {
97            strings,
98            fret_notes,
99            display_frets,
100            tuning: Vec::new(),
101        }
102    }
103
104    /// A guitar's six strings, E2 A2 D3 G3 B3 E4: music21's
105    /// `GuitarFretBoard`.
106    pub fn guitar(fret_notes: Vec<FretNote>, display_frets: usize) -> Self {
107        Self {
108            tuning: tuned(&["E2", "A2", "D3", "G3", "B3", "E4"]),
109            ..Self::new(6, fret_notes, display_frets)
110        }
111    }
112
113    /// A ukulele's four strings, re-entrant G4 C4 E4 A4: music21's
114    /// `UkeleleFretBoard`.
115    pub fn ukulele(fret_notes: Vec<FretNote>, display_frets: usize) -> Self {
116        Self {
117            tuning: tuned(&["G4", "C4", "E4", "A4"]),
118            ..Self::new(4, fret_notes, display_frets)
119        }
120    }
121
122    /// A bass guitar's four strings, E1 A1 D2 G2: music21's
123    /// `BassGuitarFretBoard`.
124    pub fn bass_guitar(fret_notes: Vec<FretNote>, display_frets: usize) -> Self {
125        Self {
126            tuning: tuned(&["E1", "A1", "D2", "G2"]),
127            ..Self::new(4, fret_notes, display_frets)
128        }
129    }
130
131    /// A mandolin's four courses, G3 D4 A4 E5: music21's
132    /// `MandolinFretBoard`.
133    pub fn mandolin(fret_notes: Vec<FretNote>, display_frets: usize) -> Self {
134        Self {
135            tuning: tuned(&["G3", "D4", "A4", "E5"]),
136            ..Self::new(4, fret_notes, display_frets)
137        }
138    }
139
140    /// The note on a string, the first if several are: music21's
141    /// `getFretNoteByString`.
142    pub fn fret_note_by_string(&self, string: IntegerType) -> Option<&FretNote> {
143        self.fret_notes
144            .iter()
145            .find(|note| note.string == Some(string))
146    }
147
148    /// The note on each string that has one, lowest-sounding string first:
149    /// music21's `fretNotesLowestFirst`.
150    pub fn fret_notes_lowest_first(&self) -> Vec<&FretNote> {
151        (1..=self.strings as IntegerType)
152            .rev()
153            .filter_map(|string| self.fret_note_by_string(string))
154            .collect()
155    }
156
157    /// The pitch each string sounds, lowest string first, nothing for a
158    /// string with no note: music21's `getPitches`. A note's pitch is its
159    /// string's open pitch raised by its fret, spelled as music21 spells a
160    /// pitch made from a number. Strings are found as music21 finds them,
161    /// counting back from the highest, so a note naming no string is read
162    /// as on the lowest.
163    ///
164    /// # Errors
165    ///
166    /// A board whose tuning is not one pitch a string, or a note on a
167    /// string the board has not got.
168    pub fn pitches(&self) -> Result<Vec<Option<Pitch>>> {
169        if self.tuning.len() != self.strings {
170            return Err(Error::Tablature(format!(
171                "Tuning must be set first, tuned for {} notes, on a {} string instrument",
172                self.tuning.len(),
173                self.strings
174            )));
175        }
176        let mut pitches: Vec<Option<Pitch>> = vec![None; self.strings];
177        for note in &self.fret_notes {
178            // music21 indexes the strings with `-string`, as Python indexes a
179            // list: string nought is the first entry and string one the
180            // last.
181            let python_index = -i64::from(note.string.unwrap_or(0));
182            let index = if python_index < 0 {
183                python_index + self.strings as i64
184            } else {
185                python_index
186            };
187            let index = usize::try_from(index)
188                .ok()
189                .filter(|index| *index < self.strings)
190                .ok_or_else(|| {
191                    Error::Tablature(format!(
192                        "string {} is not one of the {} strings",
193                        note.string.unwrap_or(0),
194                        self.strings
195                    ))
196                })?;
197            let open = self.tuning[index].ps();
198            let sounding = open + note.fret.unwrap_or(0) as FloatType;
199            pitches[index] = Some(Pitch::from_number(sounding)?);
200        }
201        Ok(pitches)
202    }
203}
204
205/// The fret a diagram starts at, and where its number is written: music21's
206/// `FirstFret`.
207#[derive(Clone, Debug, PartialEq, Eq)]
208#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
209pub struct FirstFret {
210    /// The fret.
211    pub fret: IntegerType,
212    /// Where its number goes, `right` by default.
213    pub location: String,
214}
215
216impl FirstFret {
217    /// A first fret with its number on the right.
218    pub fn new(fret: IntegerType) -> Self {
219        Self {
220            fret,
221            location: "right".to_string(),
222        }
223    }
224}
225
226/// A chord symbol with a fret diagram: music21's `ChordWithFretBoard`.
227#[derive(Clone, Debug, PartialEq)]
228#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
229pub struct ChordWithFretBoard {
230    /// The symbol.
231    pub chord_symbol: ChordSymbol,
232    /// The diagram.
233    pub fret_board: FretBoard,
234}
235
236#[cfg(test)]
237mod tests {
238    use super::*;
239
240    #[test]
241    fn fret_notes_are_written_and_ordered_as_music21_does() {
242        // music21's own tests of tablature.
243        assert_eq!(
244            FretNote::new(Some(6), Some(133), None).to_string(),
245            "6th string, 133rd fret"
246        );
247        assert_eq!(FretNote::new(None, None, None).string, None);
248        let board = FretBoard::new(
249            6,
250            vec![
251                FretNote::new(Some(1), Some(2), Some(2)),
252                FretNote::new(Some(2), Some(1), Some(1)),
253            ],
254            4,
255        );
256        let strings: Vec<Option<IntegerType>> = board
257            .fret_notes_lowest_first()
258            .iter()
259            .map(|note| note.string)
260            .collect();
261        assert_eq!(strings, [Some(2), Some(1)]);
262        assert!(board.pitches().is_err());
263    }
264
265    #[test]
266    fn a_board_sounds_its_strings_raised_by_their_frets() -> Result<()> {
267        // music21's GuitarFretBoard doctest: an A major chord.
268        let board = FretBoard::guitar(
269            vec![
270                FretNote::new(Some(3), Some(2), None),
271                FretNote::new(Some(2), Some(2), None),
272                FretNote::new(Some(4), Some(2), None),
273                FretNote::new(Some(5), Some(0), None),
274            ],
275            4,
276        );
277        let names: Vec<Option<String>> = board
278            .pitches()?
279            .iter()
280            .map(|pitch| pitch.as_ref().map(Pitch::name_with_octave))
281            .collect();
282        assert_eq!(
283            names,
284            [
285                None,
286                Some("A2".to_string()),
287                Some("E3".to_string()),
288                Some("A3".to_string()),
289                Some("C#4".to_string()),
290                None
291            ]
292        );
293        Ok(())
294    }
295}
music21/tablature.rs

music21/
tablature.rs
