arkos2basic 0.1.0b6__tar.gz → 0.1.1b1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arkos2basic
-Version: 0.1.0b6
+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.0b6 → arkos2basic-0.1.1b1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "arkos2basic"
-version = "0.1.0b6"
+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"}

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

@@ -5,7 +5,7 @@ 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__)
@@ -72,6 +72,11 @@ class BaseImport(ABC):
         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).
 
@@ -80,6 +85,10 @@ class BaseImport(ABC):
         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.
@@ -91,9 +100,25 @@ class BaseImport(ABC):
             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,
@@ -103,8 +128,27 @@ class BaseImport(ABC):
             exclude_channels=exclude_channels,
             transpose=self._transpose,
             map_instruments=map_instruments,
+            force_suffixes=force_suffixes,
+            pack=pack,
         )
 
+        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(
@@ -139,20 +183,33 @@ class BaseImport(ABC):
             )
             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.0b6 → arkos2basic-0.1.1b1}/src/arkos2basic/cli.py

@@ -12,10 +12,52 @@ 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(
@@ -98,12 +140,90 @@ def main(
                  "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()
@@ -127,6 +247,18 @@ def main(
             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).
@@ -155,6 +287,11 @@ def main(
             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)