Add MusicComposition dataclass and play_composition method

Author: dsammaruga

src/arduino/app_bricks/sound_generator/__init__.py

@@ -15,6 +15,7 @@
 from .generator import WaveSamplesBuilder
 from .effects import *
 from .loaders import ABCNotationLoader
+from .composition import MusicComposition as MusicComposition
 
 logger = Logger("SoundGenerator", logging.DEBUG)
 
@@ -591,6 +592,39 @@ def play_polyphonic(self, notes: list[list[tuple[str, float]]], as_tone: bool =
         if block and duration > 0.0:
             time.sleep(duration)
 
+    def play_composition(self, composition: "MusicComposition", block: bool = False):
+        """
+        Play a MusicComposition object.
+
+        This method configures the SoundGenerator with the composition's settings
+        and plays the polyphonic sequence.
+
+        Args:
+            composition (MusicComposition): The composition to play.
+            block (bool): If True, block until the entire composition has been played.
+
+        Example:
+            ```python
+            from arduino.app_bricks.sound_generator import MusicComposition, SoundGenerator, SoundEffect
+
+            comp = MusicComposition(
+                composition=[[("C4", 0.25), ("E4", 0.25)], [("G4", 0.5)]], bpm=120, waveform="square", volume=0.8, effects=[SoundEffect.adsr()]
+            )
+
+            gen = SoundGenerator()
+            gen.start()
+            gen.play_composition(comp, block=True)
+            ```
+        """
+        # Configure the generator with composition settings
+        self.set_bpm(composition.bpm)
+        self.set_wave_form(composition.waveform)
+        self.set_master_volume(composition.volume)
+        self.set_effects(composition.effects)
+
+        # Play the composition
+        self.play_polyphonic(composition.composition, volume=composition.volume, block=block)
+
     def play_chord(self, notes: list[str], note_duration: float | str = 1 / 4, volume: float = None, block: bool = False):
         """
         Play a chord consisting of multiple musical notes simultaneously for a specified duration and volume.

src/arduino/app_bricks/sound_generator/composition.py

@@ -0,0 +1,63 @@
+# SPDX-FileCopyrightText: Copyright (C) ARDUINO SRL (http://www.arduino.cc)
+#
+# SPDX-License-Identifier: MPL-2.0
+
+from dataclasses import dataclass, field
+from .effects import SoundEffect
+
+
+@dataclass
+class MusicComposition:
+    """
+    A structured representation of a musical composition for SoundGenerator.
+
+    This class encapsulates all the parameters needed to play a polyphonic composition,
+    making it easy to save, load, and share musical sequences.
+
+    Attributes:
+        composition (list[list[tuple[str, float]]]): Polyphonic sequence as a list of tracks.
+            Each track is a list of tuples (note, duration).
+            Duration is in note fractions (1/4 = quarter note, 1/8 = eighth note).
+            Example: [[("C4", 0.25), ("E4", 0.25)], [("G4", 0.5)]]
+        bpm (int): Tempo in beats per minute. Default: 120.
+        waveform (str): Wave form type ("sine", "square", "triangle", "sawtooth"). Default: "sine".
+        volume (float): Master volume level (0.0 to 1.0). Default: 0.8.
+        effects (list): List of SoundEffect instances to apply. Default: [SoundEffect.adsr()].
+
+    Example:
+        ```python
+        from arduino.app_bricks.sound_generator import MusicComposition, SoundGenerator, SoundEffect
+
+        # Create a composition
+        comp = MusicComposition(
+            composition=[
+                [("C4", 0.25), ("E4", 0.25), ("G4", 0.25)],  # Track 1
+                [("REST", 0.25), ("C5", 0.5)],  # Track 2
+            ],
+            bpm=120,
+            waveform="square",
+            volume=0.8,
+            effects=[SoundEffect.adsr(), SoundEffect.tremolo(depth=0.5, rate=5.0)],
+        )
+
+        # Configure and play with SoundGenerator
+        gen = SoundGenerator()
+        gen.start()
+        gen.play_composition(comp, block=True)
+
+        # Alternatively, set parameters manually and play
+        gen = SoundGenerator()
+        gen.start()
+        gen.set_bpm(comp.bpm)
+        gen.set_wave_form(comp.waveform)
+        gen.set_master_volume(comp.volume)
+        gen.set_effects(comp.effects)
+        gen.play_polyphonic(comp.composition, volume=comp.volume, block=True)
+        ```
+    """
+
+    composition: list[list[tuple[str, float]]]
+    bpm: int = 120
+    waveform: str = "sine"
+    volume: float = 0.8
+    effects: list = field(default_factory=lambda: [SoundEffect.adsr()])