arkos2basic 0.1.0b1__tar.gz

arkos2basic-0.1.0b1/PKG-INFO

@@ -0,0 +1,30 @@
+Metadata-Version: 2.4
+Name: arkos2basic
+Version: 0.1.0b1
+Summary: Converts Arkos Tracker 3 text exports to CVBasic MUSIC blocks. Handles note transposition, variable note duration, percussion detection and intro/loop splitting. Targets ColecoVision, MSX and Sega SG-1000.
+Author: Francesco Maida
+Author-email: francesco.maida@gmail.com
+Requires-Python: >=3.12,<4
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: typer (>=0.26.7,<0.27.0)
+Description-Content-Type: text/markdown
+
+# Arkos2Basic
+
+Converts Arkos Tracker 3 text exports to CVBasic MUSIC blocks. Handles note transposition, variable note duration, percussion detection and intro/loop splitting. Targets ColecoVision, MSX and Sega SG-1000.
+
+## Installation
+
+```
+pipx install arkos2basic
+```
+  
+## Usage
+
+```
+arkos2basic <input-file> <output-file>
+```
+

arkos2basic-0.1.0b1/README.md

@@ -0,0 +1,15 @@
+# Arkos2Basic
+
+Converts Arkos Tracker 3 text exports to CVBasic MUSIC blocks. Handles note transposition, variable note duration, percussion detection and intro/loop splitting. Targets ColecoVision, MSX and Sega SG-1000.
+
+## Installation
+
+```
+pipx install arkos2basic
+```
+  
+## Usage
+
+```
+arkos2basic <input-file> <output-file>
+```

arkos2basic-0.1.0b1/pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name = "arkos2basic"
+version = "0.1.0b1"
+description = "Converts Arkos Tracker 3 text exports to CVBasic MUSIC blocks. Handles note transposition, variable note duration, percussion detection and intro/loop splitting. Targets ColecoVision, MSX and Sega SG-1000."
+authors = [
+    {name = "Francesco Maida",email = "francesco.maida@gmail.com"}
+]
+readme = "README.md"
+requires-python = ">=3.12,<4"
+dependencies = [
+    "typer (>=0.26.7,<0.27.0)"
+]
+
+[tool.poetry]
+packages = [{include = "arkos2basic", from = "src"}]
+
+[tool.poetry.scripts]
+arkos2basic = "arkos2basic.cli:app"
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"

arkos2basic-0.1.0b1/src/arkos2basic/arkostracker/__init__.py

@@ -0,0 +1 @@
+"""Arkos Tracker parsing data models."""

arkos2basic-0.1.0b1/src/arkos2basic/arkostracker/baseimport.py

@@ -0,0 +1,155 @@
+"""Base class for Arkos Tracker file importers."""
+
+import logging
+from pathlib import Path
+
+from arkos2basic.arkostracker.song import Song
+from arkos2basic.cvbasic import convert
+
+
+logger = logging.getLogger(__name__)
+
+
+class BaseImport:
+    """Base importer for Arkos Tracker source files.
+
+    Subclasses implement parse() to read a specific file format and return
+    a Song. Everything else — transpose, split logic, CVBasic output — is
+    handled here and is available to every future importer for free.
+
+    Typical usage::
+
+        importer = TXTImport(input_file=path)
+        importer.transpose(effective_semitones)
+        importer.export(output_file=out, ...)
+
+    Attributes:
+        input_file: path to the source file.
+    """
+
+    def __init__(self, input_file: Path) -> None:
+        """Parse the source file and prepare the importer.
+
+        Args:
+            input_file: path to the source file to import.
+        """
+        self.input_file = input_file
+        self._song: Song = self.parse()
+        self._transpose: int = 0
+
+
+    def parse(self) -> Song:
+        """Read self.input_file and return the parsed Song.
+
+        Subclasses must override this method.
+
+        Returns:
+            A Song object with positions, patterns, tracks, and speeds.
+        """
+        raise NotImplementedError
+
+
+    def transpose(self, notes: int) -> None:
+        """Set the semitone shift applied to all melodic notes on export.
+
+        Args:
+            notes: total semitones to add (positive = up, negative = down;
+                12 = one octave up).
+        """
+        self._transpose = notes
+
+
+    def export(
+        self,
+        output_file: Path,
+        label: str,
+        data_byte: int,
+        length_scale: float,
+        invert_speed: bool,
+        stop: bool,
+        drum_length: int,
+        exclude_channels: set[int] | None = None,
+    ) -> None:
+        """Convert the song to CVBasic and write the output file(s).
+
+        Handles the intro/loop split automatically: if loop_start_position
+        > 0 and stop is False, two files are written (intro + loop).
+        Otherwise a single file is written. Status messages are emitted
+        via the module logger at INFO level.
+
+        Args:
+            output_file: path for the main output .bas file.
+            label: label assigned to the music block.
+            data_byte: frames per MUSIC step.
+            length_scale: factor for note sounding duration.
+            invert_speed: if True, high forceInstrumentSpeed = shorter note.
+            stop: if True, always end with MUSIC STOP (no split).
+            drum_length: consecutive steps per percussion hit.
+            exclude_channels: 1-based source channel indices to skip.
+        """
+        song = self._song
+        do_split = song.loop_start_position > 0 and not stop
+
+        conv_args: dict = dict(
+            data_byte=data_byte,
+            length_scale=length_scale,
+            invert_speed=invert_speed,
+            drum_length=drum_length,
+            exclude_channels=exclude_channels,
+            transpose=self._transpose,
+        )
+
+        if do_split:
+            song_end = (
+                song.end_position + 1 if song.end_position >= 0
+                else len(song.positions)
+            )
+            source_intro, speeds_intro = convert(
+                song, label=label, stop=True,
+                pos_start=0, pos_end=song.loop_start_position,
+                **conv_args,
+            )
+            loop_label = f"{label}_loop"
+            source_loop, speeds_loop = convert(
+                song, label=loop_label, stop=False,
+                pos_start=song.loop_start_position, pos_end=song_end,
+                **conv_args,
+            )
+            speeds = speeds_intro | speeds_loop
+
+            output_file.write_text(source_intro, encoding="utf-8")
+            loop_path = output_file.with_stem(output_file.stem + "_loop")
+            loop_path.write_text(source_loop, encoding="utf-8")
+
+            intro_patterns = song.loop_start_position
+            loop_patterns = song_end - song.loop_start_position
+            logger.info(
+                "Split intro/loop: %d pattern(s) intro, %d pattern(s) loop.",
+                intro_patterns,
+                loop_patterns,
+            )
+            logger.info("  Intro  -> %s  (label: %s)", output_file, label)
+            logger.info("  Loop   -> %s  (label: %s)", loop_path, loop_label)
+        else:
+            source, speeds = convert(
+                song, label=label, stop=stop, pos_start=0, **conv_args,
+            )
+            output_file.write_text(source, encoding="utf-8")
+
+            music_lines = source.count("\tMUSIC ")
+            logger.info("Converted: %d patterns.", len(song.positions))
+            logger.info(
+                "DATA BYTE: %d  ->  MUSIC rows: %d", data_byte, music_lines
+            )
+            logger.info("Output written to: %s", output_file)
+
+        logger.info(
+            "Speeds found (tracker frames/row): %s", sorted(speeds)
+        )
+        if song.drum_instruments:
+            logger.info(
+                "Percussion instruments detected: %s",
+                dict(song.drum_instruments),
+            )
+        else:
+            logger.info("No percussion instruments detected.")

arkos2basic-0.1.0b1/src/arkos2basic/arkostracker/cell.py

@@ -0,0 +1,22 @@
+"""Data model for a single Arkos Tracker cell."""
+
+from dataclasses import dataclass
+
+
+@dataclass
+class Cell:
+    """A single tracker cell.
+
+    Attributes:
+        row: row index in the pattern (vertical position).
+        note: MIDI-style note number, or -1 if absent.
+        speed: forceInstrumentSpeed value of the cell, or None.
+        instrument: instrument index (-1 if unspecified).
+            Instrument 0 ("Empty") signals an RST: the channel goes
+            silent from that row onward.
+    """
+
+    row: int
+    note: int
+    speed: int | None = None
+    instrument: int = -1

arkos2basic-0.1.0b1/src/arkos2basic/arkostracker/song.py

@@ -0,0 +1,35 @@
+"""Data model for the parsed song extracted from an Arkos Tracker file."""
+
+from dataclasses import dataclass, field
+
+from arkos2basic.arkostracker.cell import Cell
+
+
+@dataclass
+class Song:
+    """Intermediate representation of the song extracted from the file.
+
+    Attributes:
+        positions: playback order as (patternIndex, height) tuples.
+        patterns: for each patternIndex the list of 3 trackIndexes.
+        pattern_speed: for each patternIndex the speed track index.
+        tracks: for each trackIndex the list of its cells.
+        speed_tracks: for each speed track the row -> speed mapping.
+        initial_speed: starting speed before any speed-track change.
+        drum_instruments: map instrument_idx -> CVBasic type (M1/M2/M3)
+            for instruments that use the noise generator.
+        loop_start_position: 0-based index of the position from which
+            the song loops; 0 means loop from the beginning.
+        end_position: 0-based index of the last position to play
+            (inclusive); -1 means use all positions.
+    """
+
+    positions: list[tuple[int, int]] = field(default_factory=list)
+    patterns: dict[int, list[int]] = field(default_factory=dict)
+    pattern_speed: dict[int, int] = field(default_factory=dict)
+    tracks: dict[int, list[Cell]] = field(default_factory=dict)
+    speed_tracks: dict[int, dict[int, int]] = field(default_factory=dict)
+    initial_speed: int = 6
+    drum_instruments: dict[int, str] = field(default_factory=dict)
+    loop_start_position: int = 0
+    end_position: int = -1

arkos2basic-0.1.0b1/src/arkos2basic/arkostracker/txtimport.py

@@ -0,0 +1,203 @@
+"""Importer for the Arkos Tracker text export format (V1.0)."""
+
+import re
+
+from arkos2basic.arkostracker.baseimport import BaseImport
+from arkos2basic.arkostracker.cell import Cell
+from arkos2basic.arkostracker.song import Song
+
+
+class TXTImport(BaseImport):
+    """Importer for the Arkos Tracker plain-text export (V1.0).
+
+    Handles only what is specific to the TXT format: reading the
+    SECTION/ENDSECTION tree and mapping it to a Song. Split logic,
+    transpose and CVBasic output are inherited from BaseImport.
+    """
+
+    def parse(self) -> Song:
+        """Read self.input_file and parse the Arkos Tracker text.
+
+        Returns:
+            A Song object with positions, patterns, tracks, and speeds.
+        """
+        text = self.input_file.read_text(encoding="utf-8")
+        song = Song()
+        lines = text.replace("\r\n", "\n").split("\n")
+
+        stack: list[str] = []
+        track_index: int | None = None
+        cell: Cell | None = None
+        in_effect = False
+        in_track_indexes = False
+        in_speed_index = False
+        pattern_tracks: list[int] = []
+        pattern_speed_index: int | None = None
+        pattern_count = 0
+        pos_pattern: int | None = None
+        pos_height: int | None = None
+        st_index: int | None = None
+        st_row: int | None = None
+
+        inst_index: int = 0
+        in_inst_cells: bool = False
+        inst_noise_values: list[int] = []
+        inst_cell_noise: int = 0
+
+        for raw in lines:
+            line = raw.strip()
+            if not line:
+                continue
+
+            begin = re.match(r"^(-*)SECTION\s+(\w+)", line)
+            end = re.match(r"^(-*)ENDSECTION\s+(\w+)", line)
+
+            if begin:
+                name = begin.group(2)
+                stack.append(name)
+
+                if name == "track":
+                    track_index = None
+                elif name == "cell" and "track" in stack and "speedTrack" not in stack:
+                    cell = Cell(row=0, note=-1)
+                elif name == "cell" and "speedTrack" in stack:
+                    st_row = None
+                elif name == "effect":
+                    in_effect = True
+                elif name == "trackIndexes":
+                    in_track_indexes = True
+                elif name == "speedTrackIndex":
+                    in_speed_index = True
+                elif name == "speedTrack":
+                    st_index = None
+                elif name == "pattern":
+                    pattern_tracks = []
+                    pattern_speed_index = None
+                elif name == "position":
+                    pos_pattern = None
+                    pos_height = None
+                elif (name == "cells" and "instrument" in stack
+                        and "track" not in stack):
+                    in_inst_cells = True
+                    inst_noise_values = []
+                elif name == "cell" and in_inst_cells:
+                    inst_cell_noise = 0
+                continue
+
+            if end:
+                name = end.group(2)
+
+                if name == "cell" and "speedTrack" in stack:
+                    st_row = None
+                elif name == "cell" and cell is not None and "track" in stack:
+                    keep = cell.note >= 0 or cell.speed is not None
+                    if keep and track_index is not None:
+                        song.tracks.setdefault(track_index, []).append(cell)
+                    cell = None
+                elif name == "cell" and in_inst_cells:
+                    inst_noise_values.append(inst_cell_noise)
+                elif name == "effect":
+                    in_effect = False
+                elif name == "trackIndexes":
+                    in_track_indexes = False
+                elif name == "speedTrackIndex":
+                    in_speed_index = False
+                elif name == "pattern":
+                    song.patterns[pattern_count] = pattern_tracks
+                    if pattern_speed_index is not None:
+                        song.pattern_speed[pattern_count] = pattern_speed_index
+                    pattern_count += 1
+                elif name == "position":
+                    if pos_pattern is not None and pos_height is not None:
+                        song.positions.append((pos_pattern, pos_height))
+                elif (name == "cells" and "instrument" in stack
+                        and "track" not in stack):
+                    in_inst_cells = False
+                elif name == "instrument" and "instruments" in stack:
+                    noise_only = [v for v in inst_noise_values if v > 0]
+                    if noise_only:
+                        avg = sum(noise_only) / len(noise_only)
+                        song.drum_instruments[inst_index] = (
+                            self._noise_to_drum_type(avg)
+                        )
+                    inst_index += 1
+
+                if stack:
+                    stack.pop()
+                continue
+
+            parts = line.split(None, 1)
+            key = parts[0]
+            value = parts[1] if len(parts) > 1 else ""
+            top = stack[-1] if stack else ""
+
+            if "speedTrack" in stack and top == "speedTrack" and key == "index":
+                st_index = int(value)
+                song.speed_tracks.setdefault(st_index, {})
+            elif "speedTrack" in stack and top == "cell" and key == "index":
+                st_row = int(value)
+            elif "speedTrack" in stack and top == "cell" and key == "value":
+                if st_index is not None and st_row is not None:
+                    song.speed_tracks[st_index][st_row] = int(value)
+            elif top == "track" and key == "index":
+                track_index = int(value)
+                song.tracks.setdefault(track_index, [])
+            elif top == "cell" and cell is not None and key == "index":
+                cell.row = int(value)
+            elif top == "cell" and cell is not None and key == "note":
+                cell.note = int(value)
+            elif top == "cell" and cell is not None and key == "instrument":
+                cell.instrument = int(value)
+            elif in_effect and cell is not None and key == "logicalValue":
+                cell.speed = int(value)
+            elif in_speed_index and key == "trackIndex":
+                pattern_speed_index = int(value)
+            elif in_track_indexes and key == "trackIndex":
+                pattern_tracks.append(int(value))
+            elif top == "position" and key == "patternIndex":
+                pos_pattern = int(value)
+            elif top == "position" and key == "height":
+                pos_height = int(value)
+            elif top == "subsong" and key == "initialSpeed":
+                song.initial_speed = int(value)
+            elif top == "subsong" and key == "loopStartPosition":
+                song.loop_start_position = int(value)
+            elif top == "subsong" and key == "endPosition":
+                song.end_position = int(value)
+            elif in_inst_cells and top == "cell" and key == "noise":
+                inst_cell_noise = int(value)
+
+        return song
+
+
+    def transpose(self, notes: int) -> None:
+        """Set the semitone shift for all melodic notes on export.
+
+        Args:
+            notes: total semitones to add (positive = up, negative = down;
+                12 = one octave up).
+        """
+        super().transpose(notes)
+
+
+    def _noise_to_drum_type(self, avg_noise: float) -> str:
+        """Map the average noise period of an instrument to a CVBasic drum type.
+
+        The AY-3-8910 noise period ranges from 1 (high frequency) to 31
+        (low frequency). The mapping is approximate:
+        - 1-5   -> M2 (tap, snare / hi-hat)
+        - 6-15  -> M1 (strong, bass drum)
+        - 16+   -> M3 (roll, low noise)
+
+        Args:
+            avg_noise: average of the non-zero noise periods of the instrument.
+
+        Returns:
+            String "M1", "M2" or "M3" for use as the fourth MUSIC argument.
+        """
+        if avg_noise <= 5:
+            return "M2"
+        elif avg_noise <= 15:
+            return "M1"
+
+        return "M3"

arkos2basic-0.1.0b1/src/arkos2basic/cli.py

@@ -0,0 +1,139 @@
+"""Arkos Tracker text format (V1.0) to CVBasic music converter — CLI entry point.
+
+Receives command-line arguments, orchestrates the importer and the CVBasic
+exporter, and writes status messages to stdout at the end of execution.
+"""
+
+import logging
+import sys
+from io import StringIO
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from arkos2basic.arkostracker.txtimport import TXTImport
+
+
+app = typer.Typer(help="Convert an Arkos Tracker (.txt) file to CVBasic music.")
+
+
+@app.command()
+def main(
+    input_file: Annotated[
+        Path,
+        typer.Argument(help="Input Arkos Tracker file"),
+    ],
+    output_file: Annotated[
+        Path,
+        typer.Argument(help="Output .bas file"),
+    ],
+    octaves: Annotated[
+        int,
+        typer.Option(
+            help="Octave delta relative to base +1 "
+                 "(e.g. --octaves 1 → +2 octaves, --octaves -1 → 0)"
+        ),
+    ] = 0,
+    data_byte: Annotated[
+        int,
+        typer.Option(
+            help="Frames per MUSIC step: lower = more faithful but more rows "
+                 "(1 = exact timing)"
+        ),
+    ] = 2,
+    length_scale: Annotated[
+        float,
+        typer.Option(
+            "--length",
+            help="Delta from base 3.0 for note sounding duration "
+                 "(e.g. --length 1 → 4.0, --length -1 → 2.0)",
+        ),
+    ] = 0.0,
+    invert: Annotated[
+        bool,
+        typer.Option(
+            help="Invert the scale: high forceInstrumentSpeed = shorter note"
+        ),
+    ] = False,
+    label: Annotated[
+        str,
+        typer.Option(help="Label for the music block in the output source"),
+    ] = "musica",
+    stop: Annotated[
+        bool,
+        typer.Option("--stop", help="End with MUSIC STOP instead of MUSIC REPEAT"),
+    ] = False,
+    drum_length: Annotated[
+        int,
+        typer.Option(
+            help="Delta from base 2 steps per percussion hit "
+                 "(e.g. --drum-length 1 → 3, --drum-length -1 → 1)",
+        ),
+    ] = 0,
+    exclude_channels: Annotated[
+        str,
+        typer.Option(
+            "--exclude-channels",
+            help="Source channels to exclude, comma-separated "
+                 "(1-3, e.g. '2' or '2,3'). Remaining channels pack left.",
+        ),
+    ] = "",
+    transpose: Annotated[
+        int,
+        typer.Option(
+            help="Chromatic semitones to add to all notes "
+                 "(positive = up, negative = down; 12 = +1 octave).",
+        ),
+    ] = 0,
+) -> None:
+    """Command-line entry point."""
+    if data_byte < 1:
+        typer.echo("Error: --data-byte must be at least 1", err=True)
+        raise typer.Exit(1)
+
+    excluded: set[int] = set()
+    for part in exclude_channels.split(","):
+        part = part.strip()
+        if part:
+            val = int(part)
+            if val not in (1, 2, 3):
+                typer.echo(
+                    f"Error: --exclude-channels only accepts values 1, 2, 3 "
+                    f"(got: {val})",
+                    err=True,
+                )
+                raise typer.Exit(1)
+            excluded.add(val)
+
+    importer = TXTImport(input_file=input_file)
+
+    # --octaves N contributes (1 + N) * 12 semitones (base 1 octave + delta).
+    # --transpose M adds M fine semitones on top.
+    effective_transpose = (1 + octaves) * 12 + transpose
+    importer.transpose(effective_transpose)
+
+    log_buffer = StringIO()
+    log_handler = logging.StreamHandler(log_buffer)
+    log_handler.setFormatter(logging.Formatter("%(message)s"))
+    pkg_logger = logging.getLogger("arkos2basic")
+    pkg_logger.addHandler(log_handler)
+    pkg_logger.setLevel(logging.INFO)
+
+    importer.export(
+        output_file=output_file,
+        label=label,
+        data_byte=data_byte,
+        length_scale=3.0 + length_scale,
+        invert_speed=invert,
+        stop=stop,
+        drum_length=2 + drum_length,
+        exclude_channels=excluded if excluded else None,
+    )
+
+    pkg_logger.removeHandler(log_handler)
+    sys.stdout.write(log_buffer.getvalue())
+
+
+if __name__ == "__main__":
+    app()

arkos2basic-0.1.0b1/src/arkos2basic/cvbasic.py

@@ -0,0 +1,280 @@
+"""CVBasic music source generator.
+
+Contains all functions needed to emit a CVBasic DATA BYTE / MUSIC block
+from the parsed song structure (Cell, Song).
+"""
+
+from arkos2basic.arkostracker.cell import Cell  # noqa: F401
+from arkos2basic.arkostracker.song import Song  # noqa: F401
+
+
+# CVBasic places the sharp AFTER the octave number (e.g. "A4#"),
+# so each entry stores just the letter and a sharp flag.
+NOTE_NAMES: list[tuple[str, bool]] = [
+    ("C", False),
+    ("C", True),
+    ("D", False),
+    ("D", True),
+    ("E", False),
+    ("F", False),
+    ("F", True),
+    ("G", False),
+    ("G", True),
+    ("A", False),
+    ("A", True),
+    ("B", False),
+]
+
+MIN_OCTAVE: int = 2
+MAX_OCTAVE: int = 6
+
+
+def note_to_cvbasic(note: int) -> str:
+    """Convert a MIDI note number to a CVBasic note name.
+
+    The note number must already include any transposition (semitone
+    shift + octave offset) before calling this function. The octave is
+    clamped to the 2-6 range if out of bounds.
+
+    Args:
+        note: MIDI-style note number (0 = C-0), already transposed.
+
+    Returns:
+        The note name in CVBasic format, e.g. "A4#".
+    """
+    letter, sharp = NOTE_NAMES[note % 12]
+    octave = note // 12
+
+    if octave < MIN_OCTAVE:
+        octave = MIN_OCTAVE
+    elif octave > MAX_OCTAVE:
+        octave = MAX_OCTAVE
+
+    suffix = "#" if sharp else ""
+
+    return f"{letter}{octave}{suffix}"
+
+
+def build_channel(
+    cells: list[Cell],
+    height: int,
+    row_start: list[int],
+    length_scale: float,
+    invert_speed: bool,
+    drum_instruments: dict[int, str],
+    transpose: int = 0,
+) -> list[str]:
+    """Expand a channel into CVBasic tokens following the step layout.
+
+    Notes played with instrument 0 (RST) or with a percussion instrument
+    are omitted from the melodic channel (left as silence "-"); percussion
+    notes are collected separately by build_drum_channel.
+
+    Args:
+        cells: channel cells (notes and speed-only effects).
+        height: number of rows in the pattern.
+        row_start: starting step index for each row (length height + 1).
+        length_scale: factor that lengthens the sounding portion of notes.
+        invert_speed: if True, high forceInstrumentSpeed = shorter note.
+        drum_instruments: map instrument_idx -> CVBasic type; notes with
+            these instruments are silenced in the melodic channel.
+        transpose: total semitones to add to the MIDI note number
+            (includes octave shift and fine semitone adjustment).
+
+    Returns:
+        List of CVBasic tokens of length row_start[height].
+    """
+    total = row_start[height]
+    tokens: list[str] = ["-"] * total
+
+    note_cells = [c for c in cells if c.note >= 0 and c.row < height]
+    speed_at_row = {
+        c.row: c.speed for c in cells if c.speed is not None and c.row < height
+    }
+
+    for i, current in enumerate(note_cells):
+        last_speed: int | None = None
+        for r in range(current.row + 1):
+            if r in speed_at_row:
+                last_speed = speed_at_row[r]
+
+        effective = current.speed if current.speed is not None else last_speed
+
+        next_row = note_cells[i + 1].row if i + 1 < len(note_cells) else height
+        start = row_start[current.row]
+        gap = row_start[next_row] - start
+
+        if effective is None or effective == 0:
+            audible = gap
+        else:
+            base = effective
+            if invert_speed:
+                base = max(1, 12 - effective)
+            length = max(1, round(base * length_scale))
+            audible = min(length, gap)
+
+        is_silent = current.instrument == 0 or current.instrument in drum_instruments
+        if not is_silent:
+            tokens[start] = note_to_cvbasic(current.note + transpose)
+            for k in range(1, audible):
+                tokens[start + k] = "S"
+
+    return tokens
+
+
+def build_drum_channel(
+    channels_cells: list[list[Cell]],
+    row_start: list[int],
+    height: int,
+    drum_instruments: dict[int, str],
+    drum_length: int = 1,
+) -> list[str]:
+    """Build the percussion track (fourth MUSIC channel).
+
+    Scans all melodic channels of the pattern and places the percussion
+    type token at the step corresponding to the note's row, repeating it
+    for drum_length consecutive steps to make the hit more audible. If
+    more than one channel has a percussion note on the same row, the last
+    channel in the list overwrites the previous ones.
+
+    Args:
+        channels_cells: cells from each melodic channel of the pattern.
+        row_start: starting step index for each row.
+        height: number of rows in the pattern.
+        drum_instruments: map instrument_idx -> CVBasic type (M1/M2/M3).
+        drum_length: number of consecutive steps per percussion hit.
+
+    Returns:
+        List of tokens for the fourth channel, of length row_start[height].
+    """
+    total = row_start[height]
+    tokens: list[str] = ["-"] * total
+
+    for cells in channels_cells:
+        drum_cells = [
+            c for c in cells
+            if c.instrument in drum_instruments and c.row < height
+        ]
+        for cell in drum_cells:
+            drum_type = drum_instruments[cell.instrument]
+            start = row_start[cell.row]
+            for k in range(drum_length):
+                if start + k < total:
+                    tokens[start + k] = drum_type
+
+    return tokens
+
+
+def convert(
+    song: Song,
+    label: str,
+    data_byte: int,
+    length_scale: float,
+    invert_speed: bool,
+    stop: bool = False,
+    drum_length: int = 1,
+    pos_start: int = 0,
+    pos_end: int | None = None,
+    exclude_channels: set[int] | None = None,
+    transpose: int = 0,
+) -> tuple[str, set[int]]:
+    """Generate the complete CVBasic music source.
+
+    Args:
+        song: the parsed song structure.
+        label: label to assign to the music block.
+        data_byte: frames per MUSIC step (the DATA BYTE value).
+        length_scale: factor that lengthens the sounding portion.
+        invert_speed: if True, high forceInstrumentSpeed = shorter note.
+        stop: if True, end with MUSIC STOP; otherwise with MUSIC REPEAT.
+        drum_length: consecutive steps per percussion hit.
+        pos_start: index of the first position to include.
+        pos_end: exclusive index of the last position; None uses
+            end_position of the song (or the full list).
+        exclude_channels: set of 1-based source channel indices to exclude
+            (1, 2, or 3). Remaining channels are packed left; empty
+            right-hand slots become '-'.
+        transpose: total semitones to add to all melodic notes.
+
+    Returns:
+        A tuple (BASIC source string, set of speeds encountered).
+    """
+    excluded: set[int] = exclude_channels if exclude_channels is not None else set()
+
+    song_end = song.end_position + 1 if song.end_position >= 0 else len(song.positions)
+    end = pos_end if pos_end is not None else song_end
+    positions_to_play = song.positions[pos_start:end]
+
+    out: list[str] = []
+    out.append(f"{label}:")
+    out.append(
+        f"\tDATA BYTE {data_byte}"
+        f"\t' frames per step (steps/row = tracker speed / {data_byte})"
+    )
+
+    current_speed = song.initial_speed
+    speeds_seen: set[int] = set()
+
+    for pattern_index, height in positions_to_play:
+        track = song.speed_tracks.get(song.pattern_speed.get(pattern_index, -1), {})
+
+        steps_per_row: list[int] = []
+        for r in range(height):
+            if r in track and track[r] != 0:
+                current_speed = track[r]
+            speeds_seen.add(current_speed)
+            steps_per_row.append(max(1, round(current_speed / data_byte)))
+
+        row_start = [0] * (height + 1)
+        for r in range(height):
+            row_start[r + 1] = row_start[r] + steps_per_row[r]
+        total = row_start[height]
+
+        track_ids = song.patterns.get(pattern_index, [])
+        all_cells = [song.tracks.get(tid, []) for tid in track_ids]
+
+        # Filter excluded channels (1-based); remaining ones pack left,
+        # empty right-hand slots stay '-'.
+        channels_cells = [
+            cells for i, cells in enumerate(all_cells)
+            if (i + 1) not in excluded
+        ]
+
+        channels: list[list[str]] = []
+        for cells in channels_cells:
+            channels.append(
+                build_channel(
+                    cells, height, row_start,
+                    length_scale, invert_speed,
+                    song.drum_instruments, transpose,
+                )
+            )
+        while len(channels) < 3:
+            channels.append(["-"] * total)
+
+        has_drums = bool(song.drum_instruments)
+        if has_drums:
+            drums = build_drum_channel(
+                channels_cells, row_start, height,
+                song.drum_instruments, drum_length,
+            )
+
+        out.append(
+            f"\t' --- pattern {pattern_index} ({height} rows, "
+            f"speed {steps_per_row and current_speed}) ---"
+        )
+        for s in range(total):
+            if has_drums:
+                out.append(
+                    f"\tMUSIC {channels[0][s]},{channels[1][s]},"
+                    f"{channels[2][s]},{drums[s]}"
+                )
+            else:
+                out.append(
+                    f"\tMUSIC {channels[0][s]},{channels[1][s]},{channels[2][s]}"
+                )
+
+    ending = "STOP" if stop else "REPEAT"
+    out.append(f"\tMUSIC {ending}")
+
+    return "\n".join(out) + "\n", speeds_seen