rosabeats 0.1.3__py3-none-any.whl → 0.2.0__py3-none-any.whl

rosabeats/rosabeats.py

@@ -1,20 +1,25 @@
 #!/usr/bin/env python
+"""Core rosabeats module for audio beat tracking, segmentation, and remixing."""
+
+from __future__ import annotations
 
-import re
-import sys
 import os.path
 import random
-import time
-import joblib
+from typing import Any, Optional
 
-# Optional imports for vamp and ffms2
-try:
-    import vamp
-    VAMP_AVAILABLE = True
-except ImportError:
-    VAMP_AVAILABLE = False
-    vamp = None
+import joblib
+import librosa
+import numpy as np
+import scipy
+import scipy.ndimage
+import scipy.sparse.csgraph
+import sklearn
+import sklearn.cluster
+import sklearn.metrics
+import sounddevice as sd
+import soundfile as sf
 
+# Optional import for ffms2
 try:
     import ffms2
     FFMS2_AVAILABLE = True
@@ -22,23 +27,17 @@ except ImportError:
     FFMS2_AVAILABLE = False
     ffms2 = None
 
-import numpy as np
-import scipy
-import sklearn
-import librosa
-import soundfile as sf
-import sounddevice as sd
 
 class rosabeats:
     """A class for analyzing and manipulating audio files, particularly focused on beat tracking and segmentation.
-    
+
     This class provides functionality for:
     - Loading and processing audio files
     - Beat tracking and tempo analysis
     - Audio segmentation
     - Playback and remixing capabilities
     - Beat and bar manipulation
-    
+
     Attributes:
         debug (bool): Class-level debug flag for controlling debug output
         ffms_source: FFMS2 audio source object
@@ -55,7 +54,7 @@ class rosabeats:
         total_segments: Total number of segments
         segments: List of segment information
         beatsperbar: Number of beats per bar
-        firstfullbar: Index of first full bar
+        downbeat: Beat index of first downbeat (start of first full bar)
         pulse_device: PulseAudio device index
         stream: Audio output stream
         remix: Remix buffer
@@ -69,13 +68,17 @@ class rosabeats:
         sourcefile: Path to source audio file
         saved_features_enabled: Flag for saved features functionality
     """
-    
-    debug = False
+
+    debug: bool = False
+
+    # -------------------------------------------------------------------------
+    # Class methods
+    # -------------------------------------------------------------------------
 
     @classmethod
-    def d_print(cls, *args, **kwargs):
+    def d_print(cls, *args: Any, **kwargs: Any) -> None:
         """Print debug messages if debug mode is enabled.
-        
+
         Args:
             *args: Variable length argument list to print
             **kwargs: Arbitrary keyword arguments passed to print()
@@ -83,173 +86,78 @@ class rosabeats:
         if cls.debug:
             print("-> ", "".join(map(str, args)), **kwargs, flush=True)
 
-    def __init__(self, infile=None, debug=False):
+    # -------------------------------------------------------------------------
+    # Initialization
+    # -------------------------------------------------------------------------
+
+    def __init__(self, infile: Optional[str] = None, debug: bool = False) -> None:
         """Initialize the rosabeats object.
-        
+
         Args:
-            infile (str, optional): Path to input audio file
-            debug (bool, optional): Enable debug mode
+            infile: Path to input audio file
+            debug: Enable debug mode
         """
         rosabeats.debug = debug
 
-        self.ffms_source = None
-        self.data = None
-        self.sr = None
-        self.channels = None
-        self.dtype = None
-        self.mono = None
-        self.beat_timings = None
-        self.tempo = None
-        self.beat_slices = None
-        self.total_beats = None
-        self.bars = None
-        self.total_segments = None
-        self.segments = None
-        self.beatsperbar = None
-        self.firstfullbar = None
-        self.pulse_device = None
-        self.stream = None
-        self.remix = None
-        self.remix_index = None
-        self.remix_output_file = None
-        self.beats_output_file = None
-        self.beats_output = None
-        self.output_play = False
-        self.output_save = False
-        self.output_beats = False
-        self.sourcefile = None
+        self.ffms_source: Any = None
+        self.data: Optional[np.ndarray] = None
+        self.sr: Optional[int] = None
+        self.channels: Optional[int] = None
+        self.dtype: Any = None
+        self.mono: Optional[np.ndarray] = None
+        self.beat_timings: Optional[np.ndarray] = None
+        self.beat_samples: Optional[np.ndarray] = None
+        self.tempo: Optional[float] = None
+        self.beat_slices: Optional[list] = None
+        self.total_beats: Optional[int] = None
+        self.total_bars: Optional[int] = None
+        self.bars: Any = None
+        self.total_segments: Optional[int] = None
+        self.segments: Optional[list] = None
+        self.beatsperbar: Optional[int] = None
+        self.downbeat: Optional[int] = None
+        self.pulse_device: Optional[int] = None
+        self.stream: Any = None
+        self.remix: Optional[np.ndarray] = None
+        self.remix_index: Optional[int] = None
+        self.remix_output_file: Optional[str] = None
+        self.beats_output_file: Optional[str] = None
+        self.beats_output: Any = None
+        self.output_play: bool = False
+        self.output_save: bool = False
+        self.output_beats: bool = False
+        self.sourcefile: Optional[str] = None
+        self.saved_features: Optional[str] = None
 
         # things get confusing when you are experimenting a lot and forgetting
         # that it's using old features/settings that are pickled away out of sight
-        self.saved_features_enabled = False
+        self.saved_features_enabled: bool = False
 
-        if not infile is None:
+        if infile is not None:
             self.setfile(infile)
 
-    def beat_starts_bar(self, beatnum):
-        """Check if a beat number starts a new bar.
-        
-        Args:
-            beatnum (int): Beat number to check
-            
-        Returns:
-            int or None: Bar number if beat starts a bar, None otherwise
-        """
-        if (beatnum - self.firstfullbar) % self.beatsperbar == 0:
-            return (beatnum - self.firstfullbar) / self.beatsperbar
-        else:
-            return None
-
-    def bar_containing_beat(self, beatnum):
-        """Get the bar number and beat position within bar for a given beat number.
-        
-        Args:
-            beatnum (int): Beat number to analyze
-            
-        Returns:
-            tuple: (bar_number, beat_position_in_bar)
-            
-        Raises:
-            Exception: If beat number is out of range
-        """
-        if beatnum > self.total_beats - 1 or beatnum < 0:
-            raise Exception("%d is outside possible range" % beatnum)
-
-        bar = int((beatnum - self.firstfullbar) / self.beatsperbar)
-
-        if bar > self.total_bars - 1 or bar < 0:
-            raise Exception(
-                "got %d in bar %d but bar %d shouldn't exist" % (beatnum, bar)
-            )
-
-        rem = (beatnum - self.firstfullbar) % self.beatsperbar
-
-        # returns the bar and the beat # in the bar
-        return bar, rem
-
-    def set_remix_output_file(self, wavfile):
-        """Set the output file for the remix.
-        
-        Args:
-            wavfile (str): Path to output WAV file
-        """
-        self.remix_output_file = wavfile
-
-    def disable_output_beats(self):
-        """Disable beat output functionality."""
-        self.output_beats = False
-
-    def disable_output_save(self):
-        """Disable save output functionality."""
-        self.output_save = False
-
-    def disable_output_play(self):
-        """Disable playback functionality."""
-        self.output_play = False
-
-    def enable_output_beats(self, beatsfile):
-        """Enable beat output functionality and set output file.
-        
-        Args:
-            beatsfile (str): Path to output beats file
-        """
-        self.set_beats_output_file(beatsfile)
-        self.output_beats = True
-
-    def enable_output_save(self, wavfile):
-        """Enable save output functionality and set output file.
-        
-        Args:
-            wavfile (str): Path to output WAV file
-        """
-        self.set_remix_output_file(wavfile)
-        self.output_save = True
-
-    def enable_output_play(self):
-        """Enable playback functionality."""
-        self.output_play = True
-
-    def reset_remix(self):
-        """Reset the remix buffer to initial state."""
-        if self.sr is None:
-            self.load()
-
-        if self.remix is not None:
-            del self.remix
-
-        # initializes an array that will hold 30 minutes of audio samples
-        length = 30 * 60 * self.sr
-        self.remix = np.zeros(shape=(self.channels, length), dtype=self.dtype)
-        self.remix_index = 0
+    # -------------------------------------------------------------------------
+    # Property aliases for consistent naming
+    # -------------------------------------------------------------------------
 
-    def extend_remix(self):
-        """Extend the remix buffer by adding more space."""
-        if self.sr is None:
-            self.load()
+    @property
+    def beats_per_bar(self) -> Optional[int]:
+        """Alias for beatsperbar for consistent naming."""
+        return self.beatsperbar
 
-        rosabeats.d_print()
-        rosabeats.d_print("***********extending available space for remixed beats")
-        rosabeats.d_print("***********len(remix[0]) before: %s" % len(self.remix[0]))
-        # add another 30 minutes
-        length = 30 * 60 * self.sr
-        extended_array = np.concatenate(
-            (self.remix.T, np.zeros(shape=(length, self.channels), dtype=self.dtype)),
-            axis=0,
-        )
-        self.remix = extended_array.T
-        rosabeats.d_print("***********len(remix[0]) after: %s" % len(self.remix[0]))
-        rosabeats.d_print("******done extending available space for remixed beats")
+    @beats_per_bar.setter
+    def beats_per_bar(self, value: int) -> None:
+        self.beatsperbar = value
 
-    def save_remix(self):
-        """Save the remix to the output file."""
-        yt, index = librosa.effects.trim(self.remix)
-        sf.write(self.remix_output_file, yt.T, self.sr, "PCM_16")
+    # -------------------------------------------------------------------------
+    # File and path methods
+    # -------------------------------------------------------------------------
 
-    def setfile(self, infile):
+    def setfile(self, infile: str) -> None:
         """Set the input audio file and initialize related paths.
-        
+
         Args:
-            infile (str): Path to input audio file
+            infile: Path to input audio file
         """
         self.sourcefile = os.path.abspath(infile)
         dname = os.path.dirname(self.sourcefile)
@@ -257,42 +165,11 @@ class rosabeats:
         stem, _ = os.path.splitext(bname)
         self.saved_features = os.path.join(dname, "." + stem + ".pkl")
 
-    def find_pulseaudio_device(self):
-        """Find and set the PulseAudio device for playback."""
-        dev_count = 0
-        for dev_name in [x["name"] for x in sd.query_devices()]:
-            if dev_name == "pulse":
-                self.pulse_device = dev_count
-                break
-            dev_count += 1
-
-        if not self.pulse_device is None:
-            sd.default.device = self.pulse_device
-
-    def setup_playback(self):
-        """Set up audio playback configuration."""
-        if self.sr is None:
-            self.load()
-
-        sd.default.channels = self.channels
-        sd.default.samplerate = self.sr
-        sd.default.dtype = self.dtype
-
-        self.find_pulseaudio_device()
-
-        self.stream = sd.OutputStream()
-        self.stream.start()
-
-    def init_outputs(self):
-        """Initialize all enabled output methods."""
-        if self.output_play:
-            self.setup_playback()
-        if self.output_save:
-            self.reset_remix()
-        if self.output_beats:
-            self.start_writing_beats_output()
+    # -------------------------------------------------------------------------
+    # Audio loading methods
+    # -------------------------------------------------------------------------
 
-    def load_ffms(self):
+    def _load_ffms(self) -> None:
         """Load audio file using FFMS2 library."""
         self.ffms_source = ffms2.AudioSource(self.sourcefile)
         self.ffms_source.init_buffer(count=self.ffms_source.properties.NumSamples)
@@ -301,109 +178,61 @@ class rosabeats:
         self.channels = self.ffms_source.properties.Channels
         self.dtype = type(self.data[0][0])
 
-    def load_soundfile(self):
+    def _load_soundfile(self) -> None:
         """Load audio file using soundfile library."""
         self.data, self.sr = sf.read(self.sourcefile, dtype="float32")
         self.data = self.data.T
         self.channels = self.data.ndim
         self.dtype = "float32"
 
-    def load_librosa(self):
+    def _load_librosa(self) -> None:
         """Load audio file using librosa library."""
         self.data, self.sr = librosa.load(self.sourcefile, sr=None, mono=False)
         self.channels = self.data.ndim
         self.dtype = type(self.data[0][0])
 
-    def load(self):
+    def load(self) -> None:
         """Load audio file using appropriate library based on file extension.
-        
+
         Raises:
             ImportError: If FFMS2 is required but not available
         """
         base, ext = os.path.splitext(self.sourcefile)
         if ext == ".wav":
             rosabeats.d_print("loading via librosa")
-            self.load_librosa()
+            self._load_librosa()
         elif ext == ".ogg":
             rosabeats.d_print("loading via soundfile")
-            self.load_soundfile()
+            self._load_soundfile()
         else:
             if not FFMS2_AVAILABLE:
                 raise ImportError("ffms2 is required for loading non-wav/ogg files. Please install ffms2.")
             rosabeats.d_print("loading via ffms")
-            self.load_ffms()
+            self._load_ffms()
 
         self.data, _ = librosa.effects.trim(self.data)
 
-    def mix_to_mono(self):
+    def mix_to_mono(self) -> None:
         """Convert audio data to mono."""
         if self.data is None:
             self.load()
 
         self.mono = librosa.to_mono(self.data)
 
-    def has_saved_features(self):
-        """Check if saved features file exists.
-        
-        Returns:
-            bool: True if saved features file exists and is enabled
-        """
-        return self.saved_features_enabled and os.path.isfile(self.saved_features)
-
-    def remove_features_file(self):
-        """Remove the saved features file if it exists."""
-        if os.path.isfile(self.saved_features):
-            rosabeats.d_print("removing %s" % self.saved_features)
-            os.unlink(self.saved_features)
-        else:
-            rosabeats.d_print("no features file found")
-
-    def save_features(self):
-        """Save extracted features to file."""
-        rosabeats.d_print("saving features...")
-
-        features = dict()
-        features["tempo"] = self.tempo
-        features["beatsperbar"] = self.beatsperbar
-        features["firstfullbar"] = self.firstfullbar
-        features["total_beats"] = self.total_beats
-        features["total_bars"] = self.total_bars if self.total_bars else None
-        features["total_segments"] = self.total_segments
-        features["beat_timings"] = self.beat_timings
-        features["beat_samples"] = self.beat_samples
-        features["beat_slices"] = self.beat_slices
-        features["segments"] = self.segments
-        # write features
-        with open(self.saved_features, "wb") as f:
-            joblib.dump(features, f)
-
-    def load_saved_features(self):
-        """Load saved features from file."""
-        rosabeats.d_print("loading features...")
-
-        with open(self.saved_features, "rb") as f:
-            features = joblib.load(f)
-
-        self.tempo = features["tempo"]
-        self.beatsperbar = features["beatsperbar"]
-        self.firstfullbar = features["firstfullbar"]
-        self.total_beats = features["total_beats"]
-        self.total_bars = features["total_bars"]
-        self.total_segments = features["total_segments"]
-        self.beat_timings = features["beat_timings"]
-        self.beat_samples = features["beat_samples"]
-        self.beat_slices = features["beat_slices"]
-        self.segments = features["segments"]
+    # -------------------------------------------------------------------------
+    # Beat tracking methods
+    # -------------------------------------------------------------------------
 
-    def track_beats(self, beatsper=8, firstfull=0):
+    def track_beats(self, beatsper: int = 8, downbeat: int = 0) -> None:
         """Track beats in the audio file.
-        
+
         Args:
-            beatsper (int, optional): Number of beats per bar
-            firstfull (int, optional): Index of first full bar
+            beatsper: Number of beats per bar (default: 8)
+            downbeat: Beat index of first downbeat (default: 0).
+                Use detect_downbeat() for auto-detection.
         """
-        if self.has_saved_features():
-            self.load_saved_features()
+        if self._has_saved_features():
+            self._load_saved_features()
             return
 
         if self.mono is None:
@@ -419,104 +248,75 @@ class rosabeats:
         self.total_beats = len(self.beat_timings)
 
         self.beatsperbar = beatsper
-        self.firstfullbar = firstfull
-        self.total_bars = int((self.total_beats - self.firstfullbar) / self.beatsperbar)
+        self.downbeat = downbeat
 
-        self.save_features()
+        self.total_bars = int((self.total_beats - self.downbeat) / self.beatsperbar)
 
-    def segment(self, method="segmentino", redo=False, max_clusters=None):
-        """Segment the audio file using the specified method.
-        
-        Args:
-            method (str, optional): Segmentation method to use ("laplacian", "segmentino", or "backtrack"; "segmentino" is default)
-                                                               (currently, both laplacian and backtrack are broken)
-            redo (bool, optional): Force re-segmentation even if segments exist
-            
-        Raises:
-            ValueError: If invalid method is specified
-            ImportError: If method="segmentino" but vamp is not available
-            ValueError: If max_clusters is not specified for laplacian segmentation
-        """
-        if method not in ["laplacian", "segmentino", "backtrack"]:
-            raise ValueError("method must be either 'laplacian', 'segmentino' or 'backtrack'")
-            
-        if method == "segmentino" and not VAMP_AVAILABLE:
-            raise ImportError("vamp is required for segmentino segmentation. Please install vamp.")
-
-        if max_clusters is None and method == "laplacian":
-            raise ValueError("max_clusters must be specified for laplacian segmentation")
-
-        if max_clusters is not None and method != "laplacian":
-            raise ValueError("max_clusters should only be specified for laplacian segmentation")
-
-        if method == "backtrack":
-            self.segment_backtrack(redo)
-        elif method == "laplacian":
-            self.segment_laplacian(redo, max_clusters)
-        else:
-            self.segment_segmentino(redo)
+        self._save_features()
+
+    def detect_downbeat(self, beatsper: int) -> int:
+        """Detect downbeat using Dynamic Bayesian Network approach.
+
+        This uses a DBN/HMM approach for downbeat detection,
+        implemented in pure Python.
 
-    def segment_backtrack(self, redo=False):
-        """Segment audio using librosa onset detection and backtracking method.
-        
         Args:
-            redo (bool, optional): Force re-segmentation even if segments exist
+            beatsper: Number of beats per bar
+
+        Returns:
+            Beat index of the detected first downbeat
         """
-        if self.beat_timings is None:
-            self.track_beats()
+        from rosabeats.downbeat import detect_downbeat_dbn
 
-        if not self.total_segments is None and redo is False:
-            rosabeats.d_print(
-                "warning: you already have segment data and did not specify a redo"
-            )
-            return
+        if self.mono is None:
+            self.mix_to_mono()
+
+        if self.beat_timings is None:
+            raise Exception("must call track_beats first to get beat timings")
 
-        # Get onset times
-        onset_frames = librosa.onset.onset_detect(y=self.mono, sr=self.sr, backtrack=True)
+        rosabeats.d_print("detecting downbeat using DBN...")
 
-        # Initialize segments list
-        self.segments = []
-        count = 0
+        downbeat_idx = detect_downbeat_dbn(
+            self.mono, self.sr, self.beat_timings, beats_per_bar=beatsper
+        )
 
-        for frame_s, seg_len in zip(onset_frames, onset_frames[1:]):
-            segment_boundaries = (frame_s, frame_s + seg_len)
-            segment_time_boundaries = librosa.samples_to_time(segment_boundaries, sr=self.sr)
-            start, end = segment_time_boundaries
-            duration = end - start
+        rosabeats.d_print(f"DBN detected downbeat at beat {downbeat_idx}")
+        return downbeat_idx
 
-            segment = dict()
-            segment["label"] = "segment" + str(count)
-            segment["start"] = start
-            segment["duration"] = duration
-            segment["samples"] = segment_boundaries
-            segment["beats"] = []
-            segment["bars"] = []
+    # Backward compatibility alias
+    detect_downbeat_dbn = detect_downbeat
 
-            self.segments.append(segment)
+    # -------------------------------------------------------------------------
+    # Segmentation methods
+    # -------------------------------------------------------------------------
 
-            count += 1
+    def segment(self, redo: bool = False, max_clusters: int = 48) -> None:
+        """Segment the audio file using Laplacian spectral clustering.
 
-        self.total_segments = len(self.segments)
-        self.save_features()
+        Args:
+            redo: Force re-segmentation even if segments exist
+            max_clusters: Maximum clusters (default: 48)
+        """
+        self.segment_laplacian(redo, max_clusters)
 
-    def segment_laplacian(self, redo=False, max_clusters=48):
+    def segment_laplacian(self, redo: bool = False, max_clusters: int = 48) -> None:
         """Segment audio using Laplacian segmentation method.
-        
+
         Args:
-            redo (bool, optional): Force re-segmentation even if segments exist
-            max_clusters (int, optional): Maximum number of clusters to use
+            redo: Force re-segmentation even if segments exist
+            max_clusters: Maximum number of clusters to use
         """
         if self.beat_timings is None:
             self.track_beats()
 
-        if not self.total_segments is None and redo is False:
+        if self.total_segments is not None and redo is False:
             rosabeats.d_print(
                 "warning: you already have segment data and did not specify a redo"
             )
             return
 
         rosabeats.d_print("segmenting song...")
-        duration = librosa.get_duration(y=self.mono,sr=self.sr)
+        duration = librosa.get_duration(y=self.mono, sr=self.sr)
 
         beat_frames = librosa.time_to_frames(self.beat_timings, sr=self.sr)
 
@@ -524,11 +324,10 @@ class rosabeats:
         N_OCTAVES = 7
 
         cqt = librosa.cqt(y=self.mono, sr=self.sr, bins_per_octave=BINS_PER_OCTAVE, n_bins=N_OCTAVES * BINS_PER_OCTAVE)
-        C = librosa.amplitude_to_db( np.abs(cqt), ref=np.max)
+        C = librosa.amplitude_to_db(np.abs(cqt), ref=np.max)
 
         Csync = librosa.util.sync(C, beat_frames, aggregate=np.median)
 
-
         beat_times = librosa.frames_to_time(librosa.util.fix_frames(beat_frames,
                                                                     x_min=0,
                                                                     x_max=C.shape[1]),
@@ -605,7 +404,7 @@ class rosabeats:
 
                     segment_length = 1
                 else:
-                    segment_length +=1
+                    segment_length += 1
 
             ratio = float(segment_count) / float(clusters)
             min_segment_len = min(segment_lengths)
@@ -641,86 +440,46 @@ class rosabeats:
 
         self.segments = []
         prev = 0
-        for sample, label in zip(bound_samples,bound_segs):
-            segment_boundaries = (prev, sample-1)
+        for sample, label in zip(bound_samples, bound_segs):
+            segment_boundaries = (prev, sample - 1)
             prev = sample
-            segment_time_boundaries = librosa.samples_to_time(segment_boundaries,sr=self.sr)
+            segment_time_boundaries = librosa.samples_to_time(segment_boundaries, sr=self.sr)
             start, end = segment_time_boundaries
             duration = end - start
-            segment = {}
-            try:
-                segment['label'] = seg_labels[int(label)]
-            except:
-                segment['label'] = label
-
-            segment['start'] = start
-            segment['duration'] = duration
-            segment['samples'] = segment_boundaries
-            segment['beats'] = []
-            segment['bars'] = []
+            segment = {
+                'label': int(label),
+                'start': start,
+                'duration': duration,
+                'samples': segment_boundaries,
+                'beats': [],
+                'bars': [],
+            }
+            self.segments.append(segment)
 
+        # Add final segment from last boundary to end of audio
+        total_samples = len(self.mono)
+        if prev < total_samples:
+            final_label = int(seg_ids[-1])
+            segment_boundaries = (prev, total_samples - 1)
+            segment_time_boundaries = librosa.samples_to_time(segment_boundaries, sr=self.sr)
+            start, end = segment_time_boundaries
+            duration = end - start
+            segment = {
+                'label': final_label,
+                'start': start,
+                'duration': duration,
+                'samples': segment_boundaries,
+                'beats': [],
+                'bars': [],
+            }
             self.segments.append(segment)
 
         self.total_segments = len(self.segments)
-        self.save_features()
-
-        ##TODO## segment_laplacian needs to add any unsegmented part of the song as a last segment
-        ##TODO## for example, using max clusters of 10 with example audio, we get 10 segments, but ending with beat 254 (there are 308)
-        ##TODO## even if max clusters is 48, it only gives us segments including up to beat 303
-
-    def segment_segmentino(self, redo=False):
-        """Segment audio using the Segmentino plugin.
-        
-        Args:
-            redo (bool, optional): Force re-segmentation even if segments exist
-            
-        Raises:
-            RuntimeError: If segmentino plugin fails to return valid data
-        """
-        if self.data is None:
-            self.load()
+        self._save_features()
 
-        if not self.total_segments is None and redo is False:
-            rosabeats.d_print(
-                "warning: you already have segment data and did not specify a redo"
-            )
-            return
-
-        rosabeats.d_print("segmenting song...")
-        try:
-            segmented = vamp.collect(self.data, self.sr, "segmentino:segmentino")
-        except Exception as e:
-            rosabeats.d_print(f"Error loading segmentino plugin: {str(e)}")
-            raise RuntimeError(f"Failed to run segmentino segmentation: {str(e)}") from e
-        
-        if not segmented or "list" not in segmented:
-            rosabeats.d_print("Segmentino plugin returned invalid data")
-            raise RuntimeError("Segmentino plugin failed to return valid segment data")
-
-        self.total_segments = len(segmented["list"])
-        self.segments = self.total_segments * [None]
-
-        for count, result in enumerate(segmented["list"]):
-            label = result["label"]
-            start = float(result["timestamp"])
-            duration = float(result["duration"])
-            end = start + duration
-
-            self.segments[count] = dict()
-            self.segments[count]["label"] = label
-            self.segments[count]["start"] = start
-            self.segments[count]["duration"] = duration
-            self.segments[count]["samples"] = librosa.time_to_samples(
-                (start, end), sr=self.sr
-            )
-            self.segments[count]["beats"] = []
-            self.segments[count]["bars"] = []
-
-        self.save_features()
-
-    def segmentize_beats(self):
+    def segmentize_beats(self) -> None:
         """Associate beats and bars with segments.
-        
+
         Raises:
             Exception: If segments or beat timings are not available
         """
@@ -737,35 +496,26 @@ class rosabeats:
 
             # for each beat in the song...
             for beat_num in range(self.total_beats - 1):
-#               rosabeats.d_print("examining beat %d" % beat_num)
-
                 # obtain sample where beat starts
                 beat_first = self.beat_slices[beat_num][0]
-#               rosabeats.d_print("beat %d, %d <= %d <= %d ?" % (beat_num, seg_first, beat_first, seg_last))
 
                 # see if the beat starts inside the segment boundaries
                 if beat_first >= seg_first and beat_first <= seg_last:
                     # the beat starts firmly within the segment
                     # so save this beat to the list of beats associated with this segment
                     seg["beats"].append(beat_num)
-                #                   rosabeats.d_print("BEAT %d is in segment %d" % (beat_num, idx))
 
                 # now let's see if this beat starts a bar
                 bar_num = self.beat_starts_bar(beat_num)
 
                 # if it does start a bar...
-                if not bar_num is None:
-                    #                   rosabeats.d_print("beat %d starts bar %d" % (beat_num, bar_num))
-
-                    # determine the beat number of the last beat in the bar (i.e. 0 + (8-1) = 7,k so 0-7)
+                if bar_num is not None:
+                    # determine the beat number of the last beat in the bar (i.e. 0 + (8-1) = 7, so 0-7)
                     beat_num_final = int(beat_num + (self.beatsperbar - 1))
-                    #                   print("bar %d starts with beat %d and ends with beat %d" % (bar_num, beat_num, beat_num_final))
 
                     # obtain sample where final beat in bar starts
                     try:
                         beat_final_first = self.beat_slices[beat_num_final][0]
-                    #                       rosabeats.d_print("beat %d stats on sample %d" % (beat_num_final, beat_final_first))
-                    #                       rosabeats.d_print("segment starts sample %d and ends sample %d" % (seg_first, seg_last))
                     except:
                         rosabeats.d_print(
                             "warning: beat %d does not exist" % beat_num_final
@@ -775,74 +525,173 @@ class rosabeats:
                     # see if the final beat in bar starts inside the segment boundaries
                     if beat_final_first >= seg_first and beat_final_first <= seg_last:
                         # last beat starts in segment
-                        #                       rosabeats.d_print(" BAR %d is in segment %d" % (bar_num, idx))
                         seg["bars"].append(int(bar_num))
 
-                        # alternatively, bar_beat_First = self.beat_slices[beat_num_final][0]
-                        # and then check that that is <= segment, meaning last beat of bar STARTS inside segment
-        import pprint #TODO# remove
-        pprint.pprint(self.segments) #TODO# remove
-
+        self._save_features()
 
-        self.save_features()
+    # -------------------------------------------------------------------------
+    # Bar/beat calculation methods
+    # -------------------------------------------------------------------------
 
-    def divide_bars(self):
-        """Deprecated method that no longer performs any action."""
-        rosabeats.d_print("warning: divide_bars() no longer does anything")
+    def beat_starts_bar(self, beatnum: int) -> Optional[int]:
+        """Check if a beat number starts a new bar.
 
-    def set_beats_output_file(self, beatsfile):
-        """Set the output file for beat information.
-        
         Args:
-            beatsfile (str): Path to output beats file
+            beatnum: Beat number to check
+
+        Returns:
+            Bar number if beat starts a bar, None otherwise
         """
-        self.beats_output_file = beatsfile
+        if (beatnum - self.downbeat) % self.beatsperbar == 0:
+            return (beatnum - self.downbeat) // self.beatsperbar
+        else:
+            return None
 
-    def set_default_beats_output_file(self):
-        """Set default beats output file based on source filename."""
-        basename = os.path.basename(self.sourcefile)
-        stub, ext = os.path.splitext(basename)
-        self.set_beats_output_file(stub + "_beats.br")
+    def bar_containing_beat(self, beatnum: int) -> tuple[int, int]:
+        """Get the bar number and beat position within bar for a given beat number.
 
-    def start_writing_beats_output(self):
-        """Initialize beat output file and write header information."""
-        if self.beats_output_file == None:
-            self.set_default_beats_output_file()
+        Args:
+            beatnum: Beat number to analyze
 
-        self.beats_output = open(self.beats_output_file, "w")
-        self.beats_output.write("file %s\n" % self.sourcefile)
-        self.beats_output.write(
-            "beats_bar %d %d\n" % (self.beatsperbar, self.firstfullbar)
+        Returns:
+            Tuple of (bar_number, beat_position_in_bar)
+
+        Raises:
+            Exception: If beat number is out of range
+        """
+        if beatnum > self.total_beats - 1 or beatnum < 0:
+            raise Exception("%d is outside possible range" % beatnum)
+
+        bar = int((beatnum - self.downbeat) / self.beatsperbar)
+
+        if bar > self.total_bars - 1 or bar < 0:
+            raise Exception(
+                "got %d in bar %d but bar %d shouldn't exist" % (beatnum, bar, bar)
+            )
+
+        rem = (beatnum - self.downbeat) % self.beatsperbar
+
+        # returns the bar and the beat # in the bar
+        return bar, rem
+
+    # -------------------------------------------------------------------------
+    # Output configuration methods
+    # -------------------------------------------------------------------------
+
+    def _set_remix_output_file(self, wavfile: str) -> None:
+        """Set the output file for the remix.
+
+        Args:
+            wavfile: Path to output WAV file
+        """
+        self.remix_output_file = wavfile
+
+    def _set_beats_output_file(self, beatsfile: str) -> None:
+        """Set the output file for beat information.
+
+        Args:
+            beatsfile: Path to output beats file
+        """
+        self.beats_output_file = beatsfile
+
+    def _set_default_beats_output_file(self) -> None:
+        """Set default beats output file based on source filename."""
+        basename = os.path.basename(self.sourcefile)
+        stub, ext = os.path.splitext(basename)
+        self._set_beats_output_file(stub + "_beats.br")
+
+    def _start_writing_beats_output(self) -> None:
+        """Initialize beat output file and write header information."""
+        if self.beats_output_file is None:
+            self._set_default_beats_output_file()
+
+        self.beats_output = open(self.beats_output_file, "w")
+        self.beats_output.write("file %s\n" % self.sourcefile)
+        self.beats_output.write(
+            "beats_bar %d %d\n" % (self.beatsperbar, self.downbeat)
         )
 
-    def shutdown(self):
-        """Clean up and close all output streams."""
+    def enable_output_play(self) -> None:
+        """Enable playback functionality."""
+        self.output_play = True
+
+    def disable_output_play(self) -> None:
+        """Disable playback functionality."""
+        self.output_play = False
+
+    def enable_output_save(self, wavfile: str) -> None:
+        """Enable save output functionality and set output file.
+
+        Args:
+            wavfile: Path to output WAV file
+        """
+        self._set_remix_output_file(wavfile)
+        self.output_save = True
+
+    def disable_output_save(self) -> None:
+        """Disable save output functionality."""
+        self.output_save = False
+
+    def enable_output_beats(self, beatsfile: str) -> None:
+        """Enable beat output functionality and set output file.
+
+        Args:
+            beatsfile: Path to output beats file
+        """
+        self._set_beats_output_file(beatsfile)
+        self.output_beats = True
+
+    def disable_output_beats(self) -> None:
+        """Disable beat output functionality."""
+        self.output_beats = False
+
+    def init_outputs(self) -> None:
+        """Initialize all enabled output methods."""
         if self.output_play:
-            self.stream.close()
+            self.setup_playback()
         if self.output_save:
-            self.save_remix()
+            self.reset_remix()
         if self.output_beats:
-            self.beats_output.close()
+            self._start_writing_beats_output()
 
-    def write_out(self, text):
-        """Write text to beats output file.
-        
-        Args:
-            text (str): Text to write
-        """
-        if self.beats_output == None:
-            self.start_writing_beats_output()
+    # -------------------------------------------------------------------------
+    # Playback methods
+    # -------------------------------------------------------------------------
 
-        self.beats_output.write("%s\n" % text)
+    def _find_pulseaudio_device(self) -> None:
+        """Find and set the PulseAudio device for playback."""
+        dev_count = 0
+        for dev_name in [x["name"] for x in sd.query_devices()]:
+            if dev_name == "pulse":
+                self.pulse_device = dev_count
+                break
+            dev_count += 1
 
-    def play_beat(self, b, silent=False, divisor=1):
+        if self.pulse_device is not None:
+            sd.default.device = self.pulse_device
+
+    def setup_playback(self) -> None:
+        """Set up audio playback configuration."""
+        if self.sr is None:
+            self.load()
+
+        sd.default.channels = self.channels
+        sd.default.samplerate = self.sr
+        sd.default.dtype = self.dtype
+
+        self._find_pulseaudio_device()
+
+        self.stream = sd.OutputStream()
+        self.stream.start()
+
+    def play_beat(self, b: int, silent: bool = False, divisor: int = 1) -> None:
         """Play a single beat.
-        
+
         Args:
-            b (int): Beat number to play
-            silent (bool, optional): Suppress console output
-            divisor (int, optional): Beat division factor
-            
+            b: Beat number to play
+            silent: Suppress console output
+            divisor: Beat division factor
+
         Raises:
             Exception: If beat tracking has not been performed
         """
@@ -877,28 +726,8 @@ class rosabeats:
             )
 
         if self.output_save:
-            try:
-                # try copying the beat data into the existing remix buffer
-                self.remix[
-                    0,
-                    self.remix_index : self.remix_index + len(self.data[0][first:last]),
-                ] += self.data[0][first:last]
-                self.remix[
-                    1,
-                    self.remix_index : self.remix_index + len(self.data[1][first:last]),
-                ] += self.data[1][first:last]
-            except ValueError:
-                # if it fails, extend the buffer and try again
-                self.extend_remix()
-                self.remix[
-                    0,
-                    self.remix_index : self.remix_index + len(self.data[0][first:last]),
-                ] += self.data[0][first:last]
-                self.remix[
-                    1,
-                    self.remix_index : self.remix_index + len(self.data[1][first:last]),
-                ] += self.data[1][first:last]
-
+            self._copy_to_remix(0, self.data[0][first:last])
+            self._copy_to_remix(1, self.data[1][first:last])
             self.remix_index += len(self.data[0][first:last])
 
         if self.output_beats:
@@ -907,31 +736,70 @@ class rosabeats:
             else:
                 self.write_out("beats %d" % b)
 
-    def play_beats(self, beats):
+    def play_beats(self, beats: list[int]) -> None:
         """Play a sequence of beats.
-        
+
         Args:
-            beats (list): List of beat numbers to play
+            beats: List of beat numbers to play
         """
         for beat in beats:
             self.play_beat(beat)
         print(flush=True)
 
-    def play_bars(self, bars, reverse=False):
+    def play_bar(self, m: int, reverse: bool = False, silent: bool = False) -> None:
+        """Play a single bar.
+
+        Args:
+            m: Bar number to play
+            reverse: Play bar in reverse order
+            silent: Suppress console output
+
+        Raises:
+            Exception: If beat tracking has not been performed
+        """
+        if self.beatsperbar is None or self.beat_slices is None:
+            raise Exception("must track beats before you can play bar")
+
+        if self.output_beats:
+            self.write_out("# bar %d" % m)
+
+        if not silent:
+            print("[%d]" % m, end="", flush=True)
+
+        first_beat = int(m * self.beatsperbar) + self.downbeat
+        last_beat = int(first_beat + self.beatsperbar) - 1
+        if last_beat > self.total_beats - 1:
+            last_beat = int(self.total_beats) - 1
+
+        beats = [x for x in range(first_beat, last_beat + 1)]
+        if reverse:
+            if not silent:
+                print("[rev] ", end="", flush=True)
+            beats.reverse()
+
+        for beat in beats:
+            if beat == first_beat:
+                if not silent:
+                    print("*", end="", flush=True)
+            self.play_beat(beat)
+        if not silent:
+            print(flush=True)
+
+    def play_bars(self, bars: list[int], reverse: bool = False) -> None:
         """Play a sequence of bars.
-        
+
         Args:
-            bars (list): List of bar numbers to play
-            reverse (bool, optional): Play bars in reverse order
+            bars: List of bar numbers to play
+            reverse: Play bars in reverse order
         """
         for bar in bars:
             self.play_bar(bar, reverse=reverse)
 
-    def rest(self, beats):
+    def rest(self, beats: float) -> None:
         """Add silence for specified number of beats.
-        
+
         Args:
-            beats (float): Number of beats to rest
+            beats: Number of beats to rest
         """
         sec_per_beat = float(1 / (self.tempo / 60))
         sec_of_silence = sec_per_beat * beats
@@ -956,41 +824,205 @@ class rosabeats:
         if self.output_beats:
             self.write_out("rest %g" % beats)
 
-    def play_bar(self, m, reverse=False, silent=False):
-        """Play a single bar.
-        
+    # -------------------------------------------------------------------------
+    # Remix buffer methods
+    # -------------------------------------------------------------------------
+
+    def reset_remix(self) -> None:
+        """Reset the remix buffer to initial state."""
+        if self.sr is None:
+            self.load()
+
+        if self.remix is not None:
+            del self.remix
+
+        # initializes an array that will hold 30 minutes of audio samples
+        length = 30 * 60 * self.sr
+        self.remix = np.zeros(shape=(self.channels, length), dtype=self.dtype)
+        self.remix_index = 0
+
+    def _extend_remix(self) -> None:
+        """Extend the remix buffer by adding more space."""
+        if self.sr is None:
+            self.load()
+
+        rosabeats.d_print()
+        rosabeats.d_print("***********extending available space for remixed beats")
+        rosabeats.d_print("***********len(remix[0]) before: %s" % len(self.remix[0]))
+        # add another 30 minutes
+        length = 30 * 60 * self.sr
+        extended_array = np.concatenate(
+            (self.remix.T, np.zeros(shape=(length, self.channels), dtype=self.dtype)),
+            axis=0,
+        )
+        self.remix = extended_array.T
+        rosabeats.d_print("***********len(remix[0]) after: %s" % len(self.remix[0]))
+        rosabeats.d_print("******done extending available space for remixed beats")
+
+    def _copy_to_remix(self, channel: int, data: np.ndarray) -> None:
+        """Copy audio data to remix buffer, extending if necessary.
+
         Args:
-            m (int): Bar number to play
-            reverse (bool, optional): Play bar in reverse order
-            silent (bool, optional): Suppress console output
-            
-        Raises:
-            Exception: If beat tracking has not been performed
+            channel: Channel index (0 or 1 for stereo)
+            data: Audio data to copy
         """
-        if self.beatsperbar is None or self.beat_slices is None:
-            raise Exception("must track beats before you can play bar")
+        try:
+            self.remix[channel, self.remix_index:self.remix_index + len(data)] += data
+        except ValueError:
+            self._extend_remix()
+            self.remix[channel, self.remix_index:self.remix_index + len(data)] += data
 
-        if self.output_beats:
-            self.write_out("# bar %d" % m)
+    def save_remix(self) -> None:
+        """Save the remix to the output file."""
+        yt, index = librosa.effects.trim(self.remix)
+        sf.write(self.remix_output_file, yt.T, self.sr, "PCM_16")
 
-        if not silent:
-            print("[%d]" % m, end="", flush=True)
+    # -------------------------------------------------------------------------
+    # Feature caching methods
+    # -------------------------------------------------------------------------
 
-        first_beat = int(m * self.beatsperbar) + self.firstfullbar
-        last_beat = int(first_beat + self.beatsperbar) - 1
-        if last_beat > self.total_beats - 1:
-            last_beat = int(self.total_beats) - 1
+    def _has_saved_features(self) -> bool:
+        """Check if saved features file exists.
 
-        beats = [x for x in range(first_beat, last_beat + 1)]
-        if reverse:
-            if not silent:
-                print("[rev] ", end="", flush=True)
-            beats.reverse()
+        Returns:
+            True if saved features file exists and is enabled
+        """
+        return self.saved_features_enabled and os.path.isfile(self.saved_features)
 
-        for beat in beats:
-            if beat == first_beat:
-                if not silent:
-                    print("*", end="", flush=True)
-            self.play_beat(beat)
-        if not silent:
-            print(flush=True)
+    def _save_features(self) -> None:
+        """Save extracted features to file."""
+        rosabeats.d_print("saving features...")
+
+        features = dict()
+        features["tempo"] = self.tempo
+        features["beatsperbar"] = self.beatsperbar
+        features["downbeat"] = self.downbeat
+        features["total_beats"] = self.total_beats
+        features["total_bars"] = self.total_bars if self.total_bars else None
+        features["total_segments"] = self.total_segments
+        features["beat_timings"] = self.beat_timings
+        features["beat_samples"] = self.beat_samples
+        features["beat_slices"] = self.beat_slices
+        features["segments"] = self.segments
+        # write features
+        with open(self.saved_features, "wb") as f:
+            joblib.dump(features, f)
+
+    def _load_saved_features(self) -> None:
+        """Load saved features from file."""
+        rosabeats.d_print("loading features...")
+
+        with open(self.saved_features, "rb") as f:
+            features = joblib.load(f)
+
+        self.tempo = features["tempo"]
+        self.beatsperbar = features["beatsperbar"]
+        self.downbeat = features["downbeat"]
+        self.total_beats = features["total_beats"]
+        self.total_bars = features["total_bars"]
+        self.total_segments = features["total_segments"]
+        self.beat_timings = features["beat_timings"]
+        self.beat_samples = features["beat_samples"]
+        self.beat_slices = features["beat_slices"]
+        self.segments = features["segments"]
+
+    def remove_features_file(self) -> None:
+        """Remove the saved features file if it exists."""
+        if os.path.isfile(self.saved_features):
+            rosabeats.d_print("removing %s" % self.saved_features)
+            os.unlink(self.saved_features)
+        else:
+            rosabeats.d_print("no features file found")
+
+    # -------------------------------------------------------------------------
+    # Convenience methods (merged from scripts)
+    # -------------------------------------------------------------------------
+
+    def shuffle_all_beats(self, output_file: Optional[str] = None) -> None:
+        """Shuffle all beats and optionally save to file.
+
+        Args:
+            output_file: Optional path to save output WAV file
+        """
+        if self.beat_slices is None:
+            self.track_beats()
+
+        beatlist = list(range(self.total_beats))
+        random.shuffle(beatlist)
+
+        if output_file:
+            self.enable_output_save(output_file)
+            self.reset_remix()
+
+        self.play_beats(beatlist)
+
+        if output_file:
+            self.save_remix()
+
+    def shuffle_all_bars(self, output_file: Optional[str] = None) -> None:
+        """Shuffle all bars and optionally save to file.
+
+        Args:
+            output_file: Optional path to save output WAV file
+        """
+        if self.beat_slices is None:
+            self.track_beats()
+
+        barlist = list(range(self.total_bars))
+        random.shuffle(barlist)
+
+        if output_file:
+            self.enable_output_save(output_file)
+            self.reset_remix()
+
+        self.play_bars(barlist)
+
+        if output_file:
+            self.save_remix()
+
+    def reverse_beats_in_all_bars(self, output_file: Optional[str] = None) -> None:
+        """Play all bars with beats reversed within each bar.
+
+        Args:
+            output_file: Optional path to save output WAV file
+        """
+        if self.beat_slices is None:
+            self.track_beats()
+
+        if output_file:
+            self.enable_output_save(output_file)
+            self.reset_remix()
+
+        for bar in range(self.total_bars):
+            self.play_bar(bar, reverse=True)
+
+        if output_file:
+            self.save_remix()
+
+    # -------------------------------------------------------------------------
+    # Utility methods
+    # -------------------------------------------------------------------------
+
+    def write_out(self, text: str) -> None:
+        """Write text to beats output file.
+
+        Args:
+            text: Text to write
+        """
+        if self.beats_output is None:
+            self._start_writing_beats_output()
+
+        self.beats_output.write("%s\n" % text)
+
+    def shutdown(self) -> None:
+        """Clean up and close all output streams."""
+        if self.output_play:
+            self.stream.close()
+        if self.output_save:
+            self.save_remix()
+        if self.output_beats:
+            self.beats_output.close()
+
+    def divide_bars(self) -> None:
+        """Deprecated method that no longer performs any action."""
+        rosabeats.d_print("warning: divide_bars() no longer does anything")