arkos2basic 0.1.0b5__tar.gz → 0.1.1b1__tar.gz

{arkos2basic-0.1.0b5 → arkos2basic-0.1.1b1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arkos2basic
-Version: 0.1.0b5
+Version: 0.1.1b1
 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

{arkos2basic-0.1.0b5 → arkos2basic-0.1.1b1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "arkos2basic"
-version = "0.1.0b5"
+version = "0.1.1b1"
 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"}
@@ -17,6 +17,12 @@ packages = [{include = "arkos2basic", from = "src"}]
 [tool.poetry.scripts]
 arkos2basic = "arkos2basic.cli:app"
 
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.3"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
 [build-system]
 requires = ["poetry-core>=2.0.0,<3.0.0"]
 build-backend = "poetry.core.masonry.api"

{arkos2basic-0.1.0b5 → arkos2basic-0.1.1b1}/src/arkos2basic/arkostracker/baseimport.py

@@ -1,16 +1,17 @@
 """Base class for Arkos Tracker file importers."""
 
 import logging
+from abc import ABC, abstractmethod
 from pathlib import Path
 
 from arkos2basic.arkostracker.song import Song
-from arkos2basic.cvbasic import convert
+from arkos2basic.cvbasic import convert, convert_playlist
 
 
 logger = logging.getLogger(__name__)
 
 
-class BaseImport:
+class BaseImport(ABC):
     """Base importer for Arkos Tracker source files.
 
     Subclasses implement parse() to read a specific file format and return
@@ -38,6 +39,7 @@ class BaseImport:
         self._transpose: int = 0
 
 
+    @abstractmethod
     def parse(self) -> Song:
         """Read self.input_file and return the parsed Song.
 
@@ -69,6 +71,12 @@ class BaseImport:
         stop: bool,
         drum_length: int,
         exclude_channels: set[int] | None = None,
+        map_instruments: bool = True,
+        force_suffixes: dict[int, str] | None = None,
+        playlist: bool = False,
+        min_block: int = 32,
+        fuse: set[int] | None = None,
+        pack: bool = False,
     ) -> None:
         """Convert the song to CVBasic and write the output file(s).
 
@@ -77,6 +85,10 @@ class BaseImport:
         Otherwise a single file is written. Status messages are emitted
         via the module logger at INFO level.
 
+        Playlist mode replaces the split: the song is cut into reusable
+        blocks and a single file carries the blocks, the playlist and the
+        BASIC glue that chains them, looping by rewinding the playlist.
+
         Args:
             output_file: path for the main output .bas file.
             label: label assigned to the music block.
@@ -86,9 +98,27 @@ class BaseImport:
             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.
+            map_instruments: if True, Arkos instruments 1-3 are mapped
+                to the CVBasic suffixes W/X/Y.
+            force_suffixes: map of 1-based source channel index ->
+                CVBasic instrument (W/X/Y/Z) forced on that channel,
+                overriding the instrument mapping.
+            playlist: if True, deduplicate repeated stretches into
+                reusable blocks driven by a playlist.
+            min_block: shortest repeated stretch worth reusing, in steps.
+            fuse: playlist indices after which the junction is removed.
+            pack: if True, emit raw three-byte rows instead of MUSIC
+                lines; ignored (with a message) when the song has
+                percussion, which needs the fourth column.
         """
         song = self._song
-        do_split = song.loop_start_position > 0 and not stop
+
+        if pack and song.drum_instruments:
+            logger.info(
+                "Packing disabled: it drops the percussion column, and this "
+                "song uses percussion."
+            )
+            pack = False
 
         conv_args: dict = dict(
             data_byte=data_byte,
@@ -97,13 +127,30 @@ class BaseImport:
             drum_length=drum_length,
             exclude_channels=exclude_channels,
             transpose=self._transpose,
+            map_instruments=map_instruments,
+            force_suffixes=force_suffixes,
+            pack=pack,
         )
 
-        if do_split:
-            song_end = (
-                song.end_position + 1 if song.end_position >= 0
-                else len(song.positions)
+        if playlist:
+            result = convert_playlist(
+                song, label=label, stop=stop,
+                min_block=min_block, fuse=fuse,
+                include_name=output_file.name, **conv_args,
             )
+            if result is not None:
+                source, speeds = result
+                output_file.write_text(source, encoding="utf-8")
+                logger.info("Output written to: %s", output_file)
+                self._log_song_info(speeds)
+                return
+            # convert_playlist explained why; fall through to the
+            # classic single-block output.
+
+        do_split = song.loop_start_position > 0 and not stop
+
+        if do_split:
+            song_end = song.playback_end
             source_intro, speeds_intro = convert(
                 song, label=label, stop=True,
                 pos_start=0, pos_end=song.loop_start_position,
@@ -136,20 +183,33 @@ class BaseImport:
             )
             output_file.write_text(source, encoding="utf-8")
 
-            music_lines = source.count("\tMUSIC ")
+            if pack:
+                # Every step is a DATA BYTE row, minus the header and
+                # the terminator row.
+                steps = source.count("\tDATA BYTE $") - 2
+            else:
+                # Every step is a MUSIC row, minus the final STOP/REPEAT.
+                steps = source.count("\tMUSIC ") - 1
             logger.info("Converted: %d patterns.", len(song.positions))
-            logger.info(
-                "DATA BYTE: %d  ->  MUSIC rows: %d", data_byte, music_lines
-            )
+            logger.info("DATA BYTE: %d  ->  MUSIC rows: %d", data_byte, steps)
             logger.info("Output written to: %s", output_file)
 
+        self._log_song_info(speeds)
+
+
+    def _log_song_info(self, speeds: set[int]) -> None:
+        """Log the tracker speeds and the percussion instruments found.
+
+        Args:
+            speeds: the tracker speeds encountered during conversion.
+        """
         logger.info(
             "Speeds found (tracker frames/row): %s", sorted(speeds)
         )
-        if song.drum_instruments:
+        if self._song.drum_instruments:
             logger.info(
                 "Percussion instruments detected: %s",
-                dict(song.drum_instruments),
+                dict(self._song.drum_instruments),
             )
         else:
             logger.info("No percussion instruments detected.")

{arkos2basic-0.1.0b5 → arkos2basic-0.1.1b1}/src/arkos2basic/arkostracker/song.py

@@ -33,3 +33,16 @@ class Song:
     drum_instruments: dict[int, str] = field(default_factory=dict)
     loop_start_position: int = 0
     end_position: int = -1
+
+
+    @property
+    def playback_end(self) -> int:
+        """Exclusive index of the last position to play.
+
+        Returns:
+            end_position + 1 if set, otherwise the full positions length.
+        """
+        if self.end_position >= 0:
+            return self.end_position + 1
+
+        return len(self.positions)

{arkos2basic-0.1.0b5 → arkos2basic-0.1.1b1}/src/arkos2basic/arkostracker/txtimport.py

@@ -170,16 +170,6 @@ class TXTImport(BaseImport):
         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.
 

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

@@ -0,0 +1,301 @@
+"""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 pathlib import Path
+from typing import Annotated
+
+import typer
+
+from arkos2basic.arkostracker.txtimport import TXTImport
+from arkos2basic.cvbasic import MAX_DATA_BYTE
+
+
+app = typer.Typer(help="Convert an Arkos Tracker (.txt) file to CVBasic music.")
+
+# Names accepted by --channel1/2/3, plus the CVBasic letters themselves.
+CHANNEL_INSTRUMENTS: dict[str, str] = {
+    "piano": "W",
+    "clarinet": "X",
+    "flute": "Y",
+    "bass": "Z",
+    "w": "W",
+    "x": "X",
+    "y": "Y",
+    "z": "Z",
+}
+
+
+def parse_channel_instrument(value: str, option: str) -> str | None:
+    """Turn a --channelN value into the CVBasic instrument suffix.
+
+    Args:
+        value: the raw option value, empty when the option was omitted.
+        option: the option name, used in the error message.
+
+    Returns:
+        The suffix (W/X/Y/Z), or None if the option was not given.
+
+    Raises:
+        typer.Exit: if the value names no known instrument.
+    """
+    name = value.strip().lower()
+    if not name:
+        return None
+
+    suffix = CHANNEL_INSTRUMENTS.get(name)
+    if suffix is None:
+        typer.echo(
+            f"Error: {option} only accepts piano, clarinet, flute or bass "
+            f"(got: '{value}')",
+            err=True,
+        )
+        raise typer.Exit(1)
+
+    return suffix
+
+
+@app.command()
+def main(
+    input_file: Annotated[
+        Path,
+        typer.Argument(
+            help="Input Arkos Tracker file",
+            exists=True,
+            dir_okay=False,
+            readable=True,
+        ),
+    ],
+    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,
+    no_instruments: Annotated[
+        bool,
+        typer.Option(
+            "--no-instruments",
+            help="Do not map Arkos instruments 1-3 to CVBasic W/X/Y; "
+                 "all melodic notes use the default piano.",
+        ),
+    ] = False,
+    channel1: Annotated[
+        str,
+        typer.Option(
+            "--channel1",
+            help="Force one CVBasic instrument on source channel 1: "
+                 "piano, clarinet, flute or bass. Overrides the Arkos "
+                 "instrument mapping; the octave the player adds to "
+                 "clarinet and bass is compensated automatically.",
+        ),
+    ] = "",
+    channel2: Annotated[
+        str,
+        typer.Option("--channel2", help="Same as --channel1, for source channel 2."),
+    ] = "",
+    channel3: Annotated[
+        str,
+        typer.Option("--channel3", help="Same as --channel1, for source channel 3."),
+    ] = "",
+    playlist: Annotated[
+        bool,
+        typer.Option(
+            "--playlist",
+            help="Reuse repeated stretches: emit one block per unique "
+                 "stretch plus a playlist and the BASIC glue that chains "
+                 "them. Replaces the intro/loop split.",
+        ),
+    ] = False,
+    min_block: Annotated[
+        int,
+        typer.Option(
+            help="Shortest repeated stretch worth reusing, in MUSIC steps "
+                 "(--playlist only). Higher = fewer junctions.",
+        ),
+    ] = 32,
+    fuse: Annotated[
+        str,
+        typer.Option(
+            "--fuse",
+            help="Playlist entries after which the junction is removed, "
+                 "comma-separated (e.g. '2,5'). Use when a junction is "
+                 "audible; the conversion log numbers the entries.",
+        ),
+    ] = "",
+    pack: Annotated[
+        bool,
+        typer.Option(
+            "--pack3",
+            help="Emit raw 3-byte rows instead of MUSIC lines, saving 25% "
+                 "of the music ROM. Songs without percussion only.",
+        ),
+    ] = False,
+) -> 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)
+
+    if data_byte > MAX_DATA_BYTE:
+        typer.echo(
+            f"Error: --data-byte must be at most {MAX_DATA_BYTE} "
+            f"(the player keeps it in 6 bits)",
+            err=True,
+        )
+        raise typer.Exit(1)
+
+    if min_block < 1:
+        typer.echo("Error: --min-block must be at least 1", err=True)
+        raise typer.Exit(1)
+
+    fuse_set: set[int] = set()
+    for part in fuse.split(","):
+        part = part.strip()
+        if not part:
+            continue
+        try:
+            fuse_set.add(int(part))
+        except ValueError:
+            typer.echo(
+                f"Error: --fuse only accepts playlist entry numbers "
+                f"(got: '{part}')",
+                err=True,
+            )
+            raise typer.Exit(1)
+
+    excluded: set[int] = set()
+    for part in exclude_channels.split(","):
+        part = part.strip()
+        if not part:
+            continue
+        try:
+            val = int(part)
+        except ValueError:
+            typer.echo(
+                f"Error: --exclude-channels only accepts values 1, 2, 3 "
+                f"(got: '{part}')",
+                err=True,
+            )
+            raise typer.Exit(1)
+        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)
+
+    forced: dict[int, str] = {}
+    for index, value in ((1, channel1), (2, channel2), (3, channel3)):
+        suffix = parse_channel_instrument(value, f"--channel{index}")
+        if suffix is not None:
+            forced[index] = suffix
+
+    for index in sorted(set(forced) & excluded):
+        typer.echo(
+            f"Warning: --channel{index} has no effect, "
+            f"channel {index} is excluded."
+        )
+
+    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_handler = logging.StreamHandler(sys.stdout)
+    log_handler.setFormatter(logging.Formatter("%(message)s"))
+    pkg_logger = logging.getLogger("arkos2basic")
+    pkg_logger.addHandler(log_handler)
+    pkg_logger.setLevel(logging.INFO)
+
+    exclude_set: set[int] | None = None
+    if excluded:
+        exclude_set = excluded
+
+    try:
+        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=exclude_set,
+            map_instruments=not no_instruments,
+            force_suffixes=forced or None,
+            playlist=playlist,
+            min_block=min_block,
+            fuse=fuse_set,
+            pack=pack,
+        )
+    finally:
+        pkg_logger.removeHandler(log_handler)
+
+
+if __name__ == "__main__":
+    app()