.. _stdlib_strudel_scales:

====================================
Musical scales and note-name helpers
====================================

.. das:module:: strudel_scales

Module strudel_scales



++++++++++++++++++++++++
Scale and note selection
++++++++++++++++++++++++

  *  :ref:`degree_to_note (degree: int; root_midi: int; intervals: array\<int\>) : float <function-strudel_scales_degree_to_note_int_int_array_ls_int_gr_>`
  *  :ref:`get_scale_intervals_by_name (scale_type: string) : array\<int\> <function-strudel_scales_get_scale_intervals_by_name_string>`
  *  :ref:`parse_root (root_str: string) : int <function-strudel_scales_parse_root_string>`
  *  :ref:`scale (var pat: Pattern; scale_def: string) : Pattern <function-strudel_scales_scale_Pattern_string>`
  *  :ref:`scale_pattern (notation: string; scale_def: string; sound: string = "sine") : Pattern <function-strudel_scales_scale_pattern_string_string_string>`
  *  :ref:`set_scale (var pat: Pattern; scale_def: string) : Pattern <function-strudel_scales_set_scale_Pattern_string>`

.. _function-strudel_scales_degree_to_note_int_int_array_ls_int_gr_:

.. das:function:: degree_to_note(degree: int; root_midi: int; intervals: array<int>) : float

Convert a scale degree to a MIDI note number. Degree 0 = root, 1 = second, etc.;
wraps at octave boundaries so degree 7 in a major scale = root + 12. Negative
degrees wrap backwards: degree -1 in a 7-note scale is the 7th one octave down.


:Arguments: * **degree** : int

            * **root_midi** : int

            * **intervals** : array<int>

.. _function-strudel_scales_get_scale_intervals_by_name_string:

.. das:function:: get_scale_intervals_by_name(scale_type: string) : array<int>

Return the semitone-interval table for a named scale (`"major"`, `"minor"`,
`"dorian"`, `"pentatonic"`, `"blues"`, `"chromatic"`, ...). Used by tests.


:Arguments: * **scale_type** : string

.. _function-strudel_scales_parse_root_string:

.. das:function:: parse_root(root_str: string) : int

Parse a root-note string (`"C"`, `"Eb4"`, `"Fs3"`, ...) into a MIDI note number.
Default octave is 3. Exposed for tests.


:Arguments: * **root_str** : string

.. _function-strudel_scales_scale_Pattern_string:

.. das:function:: scale(pat: Pattern; scale_def: string) : Pattern

Alias for `set_scale`. Example: `n("0 2 4") |> scale("C4:major")`.


:Arguments: * **pat** :  :ref:`Pattern <alias-Pattern>`

            * **scale_def** : string

.. _function-strudel_scales_scale_pattern_string_string_string:

.. das:function:: scale_pattern(notation: string; scale_def: string; sound: string = "sine") : Pattern

Shorthand for `n(notation) |> set_scale(scale_def) |> set_sound(sound)`.
Example: `scale_pattern("0 2 4 7", "C4:pentatonic")` plays a pentatonic arpeggio.


:Arguments: * **notation** : string

            * **scale_def** : string

            * **sound** : string

.. _function-strudel_scales_set_scale_Pattern_string:

.. das:function:: set_scale(pat: Pattern; scale_def: string) : Pattern

Treat each event's `note` field as a scale degree and map it to a MIDI note
using `scale_def` (format `"Root:Type"`, e.g. `"C4:major"`, `"D:pentatonic"`).
Example: `n("0 2 4 7") |> set_scale("C4:major")` plays C, E, G, C (one octave up).


:Arguments: * **pat** :  :ref:`Pattern <alias-Pattern>`

            * **scale_def** : string