openfaba 0.1.2__py3-none-any.whl

openfaba/__init__.py

@@ -0,0 +1,6 @@
+import logging
+
+__version__ = "0.1.2"
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)

openfaba/cli.py

@@ -0,0 +1,169 @@
+import logging
+import shutil
+from pathlib import Path
+
+import typer
+from typer import Typer
+
+from openfaba.io import collect_all_mp3_files_in_folder
+from openfaba.media import (
+    deobfuscate_figure_mki_files,
+    deobfuscate_mki_library,
+    obfuscate_figure_mp3_files,
+    obfuscate_mp3_library,
+)
+
+logger = logging.getLogger(__name__)
+app = Typer(help="Create/Manage FABA figures and libraries")
+
+
+def normalize_figure_id(figure_id: str) -> str | None:
+    return f"{int(figure_id):04d}" if (figure_id.isdigit() and len(figure_id) <= 4) else None
+
+
+@app.command()
+def insert(
+    figure_id: str = typer.Option(..., "--figure-id", "-f", help="Figure ID (4 digits)"),
+    source: Path = typer.Option(..., "--source", "-s", exists=True, file_okay=False, dir_okay=True),
+    faba_library: Path = typer.Option(
+        ..., "--faba-library", "-b", exists=True, file_okay=False, dir_okay=True
+    ),
+) -> None:
+    """Create a new FABA figure from a folder of MP3 files. Fails if figure exists."""
+
+    if not (fid := normalize_figure_id(figure_id)):
+        typer.echo("figure-id must be a 4-digit number")
+        raise typer.Exit(code=1)
+
+    figure_path = faba_library / f"K{fid}"
+    if figure_path.exists():
+        if not figure_path.is_dir():
+            typer.echo(f"Error: Path for Figure K{fid} already exists as a file.")
+            raise typer.Exit(code=1)
+        elif len(list(figure_path.iterdir())) != 0:
+            typer.echo(f"Error: Figure K{fid} already exists as a not empty folder.")
+            raise typer.Exit(code=1)
+
+    if not (mp3_files := collect_all_mp3_files_in_folder(source)):
+        typer.echo("No MP3 files found in the source folder.")
+        raise typer.Exit(code=1)
+
+    obfuscate_figure_mp3_files(fid, mp3_files, faba_library)
+    typer.echo(f"Inserted figure K{fid}. Added {len(mp3_files)} tracks.")
+
+
+@app.command()
+def extend(
+    figure_id: str = typer.Option(..., "--figure-id", "-f", help="Figure ID (4 digits)"),
+    source: Path = typer.Option(..., "--source", "-s", exists=True, file_okay=False, dir_okay=True),
+    faba_library: Path = typer.Option(
+        ..., "--faba-library", "-b", exists=True, file_okay=False, dir_okay=True
+    ),
+) -> None:
+    """Append MP3 files to an existing figure. Does not overwrite existing tracks."""
+
+    if not (fid := normalize_figure_id(figure_id)):
+        typer.echo("figure-id must be a 4-digit number")
+        raise typer.Exit(code=1)
+
+    figure_path = faba_library / f"K{fid}"
+    if not figure_path.exists():
+        typer.echo(f"Error: Figure K{fid} does not exist in the library.")
+        raise typer.Exit(code=1)
+
+    if not (mp3_files := collect_all_mp3_files_in_folder(source)):
+        typer.echo("No MP3 files found in the source folder.")
+        raise typer.Exit(code=1)
+
+    obfuscate_figure_mp3_files(fid, mp3_files, faba_library, append=True)
+
+    typer.echo(f"Extended figure K{fid}. Appended {len(mp3_files)} tracks.")
+
+
+@app.command()
+def replace(
+    figure_id: str = typer.Option(..., "--figure-id", "-f", help="Figure ID (4 digits)"),
+    source: Path = typer.Option(..., "--source", "-s", exists=True, file_okay=False, dir_okay=True),
+    faba_library: Path = typer.Option(
+        ..., "--faba-library", "-b", exists=True, file_okay=False, dir_okay=True
+    ),
+) -> None:
+    """Delete an existing figure and recreate it from MP3 files."""
+
+    if not (fid := normalize_figure_id(figure_id)):
+        typer.echo("figure-id must be a 4-digit number")
+        raise typer.Exit(code=1)
+
+    figure_path = faba_library / f"K{fid}"
+    if figure_path.exists():
+        try:
+            shutil.rmtree(figure_path)
+        except Exception as exc:
+            typer.echo(f"Error removing existing figure: {exc}", err=True)
+            raise typer.Exit(code=1) from exc
+
+    if not (mp3_files := collect_all_mp3_files_in_folder(source)):
+        typer.echo("No MP3 files found in the source folder.")
+        raise typer.Exit(code=1)
+
+    obfuscate_figure_mp3_files(fid, mp3_files, faba_library)
+    typer.echo(f"Replaced figure K{fid}. Created with {len(mp3_files)} tracks.")
+
+
+@app.command()
+def extract(
+    figure_id: str = typer.Option(..., "--figure-id", "-f", help="Figure ID (4 digits)"),
+    faba_library: Path = typer.Option(
+        ..., "--faba-library", "-b", exists=True, file_okay=False, dir_okay=True
+    ),
+    output: Path = typer.Option(..., "--output", "-o", file_okay=False, dir_okay=True),
+) -> None:
+    """Extract a single figure from a FABA library into MP3 files."""
+
+    if not (fid := normalize_figure_id(figure_id)):
+        typer.echo("figure-id must be a 4-digit number")
+        raise typer.Exit(code=1)
+    output.mkdir(parents=True, exist_ok=True)
+
+    converted = deobfuscate_figure_mki_files(fid, faba_library, output)
+    if converted == 0:
+        typer.echo(f"No MKI files found for figure K{fid}.")
+        raise typer.Exit(code=1)
+
+    typer.echo(f"Extracted figure K{fid}. Converted {converted} files.")
+
+
+@app.command()
+def obfuscate(
+    mp3_library: Path = typer.Option(
+        ..., "--mp3-library", "-m", exists=True, file_okay=False, dir_okay=True
+    ),
+    faba_library: Path = typer.Option(
+        ..., "--faba-library", "-b", exists=True, file_okay=False, dir_okay=True
+    ),
+) -> None:
+    """Obfuscate an entire MP3 library into a FABA MKI library."""
+    converted = obfuscate_mp3_library(mp3_library, faba_library)
+    if converted == 0:
+        typer.echo("No MP3 files found in the source library.")
+        raise typer.Exit(code=1)
+
+    typer.echo(f"Obfuscated library. Converted {converted} files.")
+
+
+@app.command()
+def deobfuscate(
+    faba_library: Path = typer.Option(
+        ..., "--faba-library", "-b", exists=True, file_okay=False, dir_okay=True
+    ),
+    mp3_library: Path = typer.Option(..., "--mp3-library", "-m", file_okay=False, dir_okay=True),
+) -> None:
+    """Deobfuscate an entire FABA MKI library back into MP3 files."""
+    mp3_library.mkdir(parents=True, exist_ok=True)
+
+    converted = deobfuscate_mki_library(faba_library, mp3_library)
+    if converted == 0:
+        typer.echo("No MKI files found in the FABA library.")
+        raise typer.Exit(code=1)
+
+    typer.echo(f"Deobfuscated library. Converted {converted} files.")

openfaba/consts.py

@@ -0,0 +1,152 @@
+BYTE_HIGH_NIBBLE = [
+    [
+        0x30,
+        0x30,
+        0x20,
+        0x20,
+        0x10,
+        0x10,
+        0x00,
+        0x00,
+        0x70,
+        0x70,
+        0x60,
+        0x60,
+        0x50,
+        0x50,
+        0x40,
+        0x40,
+        0xB0,
+        0xB0,
+        0xA0,
+        0xA0,
+        0x90,
+        0x90,
+        0x80,
+        0x80,
+        0xF0,
+        0xF0,
+        0xE0,
+        0xE0,
+        0xD0,
+        0xD0,
+        0xC0,
+        0xC0,
+    ],
+    [
+        0x00,
+        0x00,
+        0x10,
+        0x10,
+        0x20,
+        0x20,
+        0x30,
+        0x30,
+        0x40,
+        0x40,
+        0x50,
+        0x50,
+        0x60,
+        0x60,
+        0x70,
+        0x70,
+        0x80,
+        0x80,
+        0x90,
+        0x90,
+        0xA0,
+        0xA0,
+        0xB0,
+        0xB0,
+        0xC0,
+        0xC0,
+        0xD0,
+        0xD0,
+        0xE0,
+        0xE0,
+        0xF0,
+        0xF0,
+    ],
+    [
+        0x10,
+        0x10,
+        0x00,
+        0x00,
+        0x30,
+        0x30,
+        0x20,
+        0x20,
+        0x50,
+        0x50,
+        0x40,
+        0x40,
+        0x70,
+        0x70,
+        0x60,
+        0x60,
+        0x90,
+        0x90,
+        0x80,
+        0x80,
+        0xB0,
+        0xB0,
+        0xA0,
+        0xA0,
+        0xD0,
+        0xD0,
+        0xC0,
+        0xC0,
+        0xF0,
+        0xF0,
+        0xE0,
+        0xE0,
+    ],
+    [
+        0x20,
+        0x20,
+        0x30,
+        0x30,
+        0x00,
+        0x00,
+        0x10,
+        0x10,
+        0x60,
+        0x60,
+        0x70,
+        0x70,
+        0x40,
+        0x40,
+        0x50,
+        0x50,
+        0xA0,
+        0xA0,
+        0xB0,
+        0xB0,
+        0x80,
+        0x80,
+        0x90,
+        0x90,
+        0xE0,
+        0xE0,
+        0xF0,
+        0xF0,
+        0xC0,
+        0xC0,
+        0xD0,
+        0xD0,
+    ],
+]
+
+BYTE_LOW_NIBBLE_EVEN = [
+    [0x0, 0x1, 0x2, 0x3, 0x4, 0x5, 0x6, 0x7],
+    [0x5, 0x4, 0x7, 0x6, 0x1, 0x0, 0x3, 0x2],
+    [0x9, 0x8, 0xB, 0xA, 0xD, 0xC, 0xF, 0xE],
+    [0x0, 0x1, 0x2, 0x3, 0x4, 0x5, 0x6, 0x7],
+]
+
+BYTE_LOW_NIBBLE_ODD = [
+    [0x8, 0x9, 0xA, 0xB, 0xC, 0xD, 0xE, 0xF],
+    [0xD, 0xC, 0xF, 0xE, 0x9, 0x8, 0xB, 0xA],
+    [0x1, 0x0, 0x3, 0x2, 0x5, 0x4, 0x7, 0x6],
+    [0x8, 0x9, 0xA, 0xB, 0xC, 0xD, 0xE, 0xF],
+]

openfaba/io.py

@@ -0,0 +1,94 @@
+import logging
+import sys
+from pathlib import Path
+
+from mutagen.id3 import ID3, TIT2  # type:ignore [attr-defined]
+from mutagen.mp3 import MP3
+
+from openfaba.consts import BYTE_HIGH_NIBBLE, BYTE_LOW_NIBBLE_EVEN, BYTE_LOW_NIBBLE_ODD
+from openfaba.utils import allow_invalid_synchsafe_in_mutagen
+
+logger = logging.getLogger(__name__)
+
+
+def clear_tags_and_set_title(mp3_file: Path, new_title: str) -> None:
+    """Remove all MP3 tags and set a single title tag"""
+    try:
+        _clear_tags_and_set_title(mp3_file, new_title)
+        logger.info(f"Title updated for {mp3_file}")
+    except Exception as e:
+        logger.error(f"Error processing {mp3_file}: {e}")
+        sys.exit(1)
+
+
+def convert_mp3_to_mki(mp3_file: Path, mki_file: Path) -> None:
+    """Apply custom byte transformation to an mp3 file"""
+    try:
+        _convert_mp3_to_mki(mp3_file, mki_file)
+        logger.info(f"Conversion complete. Output file: {mki_file}")
+    except IOError as e:
+        logger.error(f"Error processing {mp3_file}: {e}")
+        sys.exit(1)
+
+
+def convert_mki_to_mp3(mki_file: Path, mp3_file: Path) -> None:
+    """Reverse the custom byte transformation to restore the original mp3 file"""
+    try:
+        _convert_mki_to_mp3(mki_file, mp3_file)
+        logger.info(f"Conversion complete. Output file: {mp3_file}")
+    except IOError as e:
+        logger.error(f"Error processing {mki_file}: {e}")
+        sys.exit(1)
+
+
+def collect_all_mp3_files_in_folder(source: Path) -> list[Path]:
+    return sorted(p for p in source.rglob("*.mp3") if p.is_file())
+
+
+def _clear_tags_and_set_title(mp3_file: Path, new_title: str) -> None:
+    with allow_invalid_synchsafe_in_mutagen():
+        tags = MP3(mp3_file, ID3=ID3)
+        # If title already matches, skip to preserve exact original bytes
+        if "TIT2" in tags and len(tags) == 1 and str(tags["TIT2"].text[0]) == new_title:
+            return
+
+        # Ensure we write the title as UTF-16 (Encoding 1) and as a list of text
+        tags.delete()
+        tags["TIT2"] = TIT2(encoding=1, text=[new_title])
+        tags.save(v2_version=3, padding=lambda x: 0)
+
+
+def _convert_mp3_to_mki(mp3_file: Path, mki_file: Path) -> None:
+    with mp3_file.open("rb") as infile, mki_file.open("wb") as outfile:
+        for pos, byte in enumerate(infile.read()):
+            byte_pos = pos % 4
+
+            high_index = byte % 32
+            low_index = byte // 32
+
+            modified_byte = BYTE_HIGH_NIBBLE[byte_pos][high_index]
+
+            if byte % 2 == 0:
+                modified_byte += BYTE_LOW_NIBBLE_EVEN[byte_pos][low_index]
+            else:
+                modified_byte += BYTE_LOW_NIBBLE_ODD[byte_pos][low_index]
+
+            outfile.write(bytes((modified_byte,)))
+
+
+def _convert_mki_to_mp3(mki_file: Path, mp3_file: Path) -> None:
+    with mki_file.open("rb") as infile, mp3_file.open("wb") as outfile:
+        for pos, byte in enumerate(infile.read()):
+            byte_pos = pos % 4
+
+            high_byte = byte & 0xF0
+            low_byte = byte & 0x0F
+
+            index_high = BYTE_HIGH_NIBBLE[byte_pos].index(high_byte)
+            if low_byte in BYTE_LOW_NIBBLE_EVEN[byte_pos]:
+                index_low = BYTE_LOW_NIBBLE_EVEN[byte_pos].index(low_byte)
+            else:
+                index_low = BYTE_LOW_NIBBLE_ODD[byte_pos].index(low_byte)
+                index_high += 1
+
+            outfile.write(bytes((index_low * 32 + index_high,)))

openfaba/main.py

@@ -0,0 +1,9 @@
+from openfaba.cli import app
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()

openfaba/media.py

@@ -0,0 +1,196 @@
+import logging
+import re
+import shutil
+import tempfile
+from collections import defaultdict
+from pathlib import Path
+
+from openfaba.io import clear_tags_and_set_title, convert_mki_to_mp3, convert_mp3_to_mki
+
+logger = logging.getLogger(__name__)
+
+
+def obfuscate_figure_mp3_files(
+    figure_id: str, source_mp3_files: list[Path], faba_library: Path, append: bool = False
+) -> None:
+    """
+    Obfuscate a sequence of MP3 files for a single Faba figure.
+
+    Each MP3 file is copied to a temporary location, stripped of metadata,
+    assigned a deterministic title, and converted to the proprietary MKI format.
+    Resulting files are written into the corresponding figure folder inside
+    the Faba library (e.g. ``K0104``).
+
+    Parameters
+    ----------
+    figure_id:
+        Four-digit Faba figure identifier (e.g. ``"0104"``).
+    source_mp3_files:
+        Ordered collection of source MP3 files to obfuscate for this figure.
+    faba_library:
+        Root path of the target Faba library (typically an ``MKI01`` folder).
+    append:
+        When True, MP3 files will be appended to an existing figure. New
+        tracks are numbered after the highest existing ``.MKI`` file. When
+        False (default) the figure will be created/overwritten starting at
+        track 1.
+    """
+    if not source_mp3_files:
+        logger.warning("No MP3 files provided for figure `%s`", figure_id)
+        return
+
+    logger.info("Converting files for figure: `%s`", figure_id)
+
+    figure_path = faba_library / f"K{figure_id}"
+    if append and not figure_path.exists():
+        raise ValueError("You cannot append tracks to an unexisting figure")
+    figure_path.mkdir(parents=True, exist_ok=True)
+
+    existing_mki = sorted(p for p in figure_path.iterdir() if p.suffix.lower() == ".mki")
+    start_index = (len(existing_mki) + 1) if append else 1
+
+    for index, mp3_file in enumerate(sorted(source_mp3_files), start=start_index):
+        logger.info(
+            "Converting file %s [%d/%d]",
+            mp3_file.name,
+            index - start_index + 1,
+            len(source_mp3_files),
+        )
+
+        file_number = f"{index:02d}"
+
+        temp_handle = tempfile.NamedTemporaryFile(suffix=".mp3", delete=False)
+        temp_mp3 = Path(temp_handle.name)
+        temp_handle.close()  # Required for Windows compatibility
+
+        try:
+            shutil.copy(mp3_file, temp_mp3)
+
+            new_title = f"K{figure_id}CP{file_number}"
+            clear_tags_and_set_title(temp_mp3, new_title)
+
+            obfuscated_file = figure_path / f"CP{file_number}.MKI"
+            convert_mp3_to_mki(temp_mp3, obfuscated_file)
+        finally:
+            temp_mp3.unlink(missing_ok=True)
+
+
+def obfuscate_mp3_library(
+    faba_library_mp3: Path, faba_library: Path, default_figure_id: str = "0000"
+) -> int:
+    """
+    Obfuscate a directory tree of MP3 files into a Faba-compatible MKI library.
+
+    MP3 files are discovered recursively. If a file resides inside a directory
+    named ``K####``, the digits are interpreted as the figure identifier.
+    Otherwise, ``default_figure_id`` is used.
+
+    Parameters
+    ----------
+    faba_library_mp3:
+        Path containing source MP3 files. Subfolders named ``K####`` will be
+        interpreted as per-figure groupings.
+    faba_library:
+        Destination Faba library root directory (typically an ``MKI01`` folder).
+        Per-figure subfolders (e.g. ``K0104``) will be created as needed.
+    default_figure_id:
+        Figure identifier to use when no ``K####`` directory can be inferred.
+
+    Returns
+    -------
+    int
+        Total number of MP3 files processed.
+    """
+    # Monkeypatch to tolerate malformed ID3 headers
+
+    all_mp3_files = sorted(p for p in faba_library_mp3.rglob("*") if p.suffix.lower() == ".mp3")
+    files_by_figure: defaultdict[str, list[Path]] = defaultdict(list)
+
+    for mp3_file in all_mp3_files:
+        match = re.search(r"K(\d{4})$", mp3_file.parent.name)
+        figure_id = match.group(1) if match else default_figure_id
+        files_by_figure[figure_id].append(mp3_file)
+
+    for figure_id, figure_mp3_files in files_by_figure.items():
+        obfuscate_figure_mp3_files(figure_id, figure_mp3_files, faba_library)
+
+    return len(all_mp3_files)
+
+
+def deobfuscate_figure_mki_files(figure_id: str, faba_library: Path, output_folder: Path) -> int:
+    """
+    Deobfuscate all MKI files for a single Faba figure into MP3 files.
+
+    MKI files are read from the corresponding figure directory inside the
+    Faba library (e.g. ``K0104``) and converted back to standard MP3 files.
+    The resulting MP3 files are written into a mirrored figure directory
+    under the ``output_folder`` path.
+
+    Parameters
+    ----------
+    figure_id:
+        Four-digit Faba figure identifier (e.g. ``"0104"``).
+    faba_library:
+        Root path of the source Faba library (typically an ``MKI01`` folder).
+    output_folder:
+        Root path where deobfuscated MP3 files will be written.
+
+    Returns
+    -------
+    int
+        Number of MKI files converted for this figure.
+    """
+    figure_path = faba_library / f"K{figure_id}"
+    if not figure_path.exists():
+        logger.warning("Figure directory not found for figure `%s`", figure_id)
+        return 0
+
+    mki_files = sorted(p for p in figure_path.iterdir() if p.suffix.lower() == ".mki")
+
+    if not mki_files:
+        logger.warning("No MKI files found for figure `%s`", figure_id)
+        return 0
+
+    target_figure_path = output_folder / f"K{figure_id}"
+    target_figure_path.mkdir(parents=True, exist_ok=True)
+
+    for index, mki_file in enumerate(mki_files, start=1):
+        target_file = (target_figure_path / mki_file.name).with_suffix(".mp3")
+        logger.info("Converting file %s [%d/%d]", mki_file.name, index, len(mki_files))
+        convert_mki_to_mp3(mki_file, target_file)
+
+    return len(mki_files)
+
+
+def deobfuscate_mki_library(faba_library: Path, faba_library_mp3: Path) -> int:
+    """
+    Deobfuscate a Faba MKI library back into standard MP3 files.
+
+    MKI files are discovered recursively inside the Faba library. The original
+    folder structure is preserved in the output directory, with file extensions
+    converted to ``.mp3``.
+
+    Parameters
+    ----------
+    faba_library:
+        Source Faba library root directory (typically an ``MKI01`` folder)
+        containing per-figure subdirectories with ``.MKI`` files.
+    faba_library_mp3:
+        Destination directory where deobfuscated MP3 files will be written.
+
+    Returns
+    -------
+    int
+        Total number of MKI files converted.
+    """
+    mki_files = sorted(p for p in faba_library.rglob("*") if p.suffix.lower() == ".mki")
+
+    for index, mki_file in enumerate(mki_files, start=1):
+        relative_path = mki_file.relative_to(faba_library)
+        target_file = (faba_library_mp3 / relative_path).with_suffix(".mp3")
+        target_file.parent.mkdir(parents=True, exist_ok=True)
+
+        logger.info("Converting file %s [%d/%d]", mki_file.name, index, len(mki_files))
+        convert_mki_to_mp3(mki_file, target_file)
+
+    return len(mki_files)

openfaba/utils.py

@@ -0,0 +1,18 @@
+from contextlib import contextmanager
+from typing import Iterator
+
+from mutagen.id3._util import BitPaddedInt
+
+
+@contextmanager
+def allow_invalid_synchsafe_in_mutagen() -> Iterator[None]:
+    """
+    Temporarily disable synchsafe integer validation.
+    Intended only for ID3 deletion paths.
+    """
+    orig = BitPaddedInt.has_valid_padding
+    BitPaddedInt.has_valid_padding = lambda *_: True  # type: ignore[method-assign]
+    try:
+        yield
+    finally:
+        BitPaddedInt.has_valid_padding = orig  # type: ignore[method-assign]

openfaba-0.1.2.dist-info/METADATA

@@ -0,0 +1,231 @@
+Metadata-Version: 2.4
+Name: openfaba
+Version: 0.1.2
+Summary: A modern reimplementation of redele.
+Author-email: Gustavo Viera López <gvieralopez@gmail.com>
+License: MIT
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.9.0
+Requires-Dist: mutagen>=1.47.0
+Dynamic: license-file
+
+# openFABA
+
+**openFABA** is a command-line tool for inspecting, extracting, and exporting audio 
+files for the **FABA** storytelling box. It allows you to convert standard MP3 files 
+into FABA-compatible files for specific figures.
+
+This project builds upon the reverse-engineering work by
+[wansors](https://github.com/wansors/myfaba-hacks/blob/main/python/redele.py).
+At the moment, openFABA supports **only the original FABA device**.
+
+### Disclaimer
+
+openFABA is an independent project and is **not affiliated with or endorsed by FABA**.
+
+This software is provided *as is*, without warranties of any kind. You are responsible 
+for how you use it and for any consequences that may arise, including device malfunction 
+or account-related actions. Some features may conflict with FABA’s terms of service or 
+usage policies.
+
+The goal of openFABA is to:
+
+* simplify the creation of custom, FABA-compatible figures
+* enable personalization of figures you already own
+
+We do **not** endorse music piracy, copyright infringement, or any misuse that could 
+negatively impact FABA or its ecosystem. FABA is a great company, and we encourage 
+supporting them by purchasing their products.
+
+Use this tool responsibly and at your own risk.
+
+
+## 🚀 Prerequisites
+
+Before working with this project, make sure you have [uv](https://docs.astral.sh/uv/) installed. 👉 Install guide: [uv docs](https://docs.astral.sh/uv/getting-started/installation/)
+
+If you are a developer and want to contribute to this project, you may want to have 
+[make](https://www.gnu.org/software/make/) installed as well.
+
+
+## ⚡ Installation
+
+Install dependencies into a local virtual environment:
+
+```bash
+uv sync --all-groups
+```
+
+Then, to activate the virtual environment:
+
+On Linux / macOS:
+
+```bash
+source .venv/bin/activate
+```
+
+On Windows (PowerShell):
+
+```powershell
+.venv\Scripts\Activate.ps1
+# If your PowerShell execution policy prevents running the script, run:
+powershell -ExecutionPolicy Bypass -File .venv\Scripts\Activate.ps1
+```
+
+On Windows (CMD):
+
+```cmd
+.venv\Scripts\activate.bat
+```
+
+## 🛠️ Usage
+
+### Create your own figure
+
+Create a new FABA figure from a folder containing MP3 files. The target figure must 
+not already exist in the FABA library, otherwise the command will fail to avoid 
+accidental overwrites.
+
+For example, to create a new FABA figure with ID `4742` using the songs in `/home/user/songs` 
+and copy it to the FABA box mounted at `/mnt/faba/MKI01`, run:
+
+```bash
+openfaba insert \
+  --figure-id 4742 \
+  --source /home/user/songs \
+  --faba-library /mnt/faba/MKI01
+```
+
+Write an NFC TAG with the figure ID and enjoy it! If you need help on how todo it, 
+[these FAQs](https://github.com/wansors/myfaba-hacks/blob/main/FAQ.md) from the original 
+wansors' project have a lot of useful information.
+
+### Add songs to an existing figure
+
+Append additional MP3 files to an already existing figure. New tracks are added after the 
+existing ones and never overwrite previously stored audio.
+
+```bash
+openfaba extend \
+  --figure-id 4742 \
+  --source /home/user/new_songs \
+  --faba-library /mnt/faba/MKI01
+```
+
+
+### Replace a figure
+
+Delete an existing figure and recreate it from scratch using a new set of MP3 files. This 
+operation removes the previous contents of the figure.
+
+```bash
+openfaba replace \
+  --figure-id 4742 \
+  --source /home/user/songs \
+  --faba-library /mnt/faba/MKI01
+```
+
+
+### Listen to some FABA songs on your computer
+
+Extract (deobfuscate) a single figure from a FABA box and convert it back to standard MP3 
+files so they can be played on a computer or mobile device.
+
+For example, to extract the Italian red elephant **Ele** (figure ID `0010`):
+
+```bash
+openfaba extract \
+  --figure-id 0010 \
+  --faba-library /mnt/faba/MKI01 \
+  --output /home/user/elephant_ele
+```
+
+
+### Obfuscate an entire MP3 library
+
+Convert a directory tree of MP3 files into a FABA-compatible MKI library. Subfolders named 
+`K####` are interpreted as figure IDs; otherwise a default figure ID is used.
+
+```bash
+openfaba obfuscate \
+  --mp3-library /home/user/mp3_library \
+  --faba-library /mnt/faba/MKI01
+```
+
+
+### Deobfuscate an entire FABA library
+
+Convert all figures from a FABA MKI library back into MP3 files, preserving the original 
+folder structure.
+
+```bash
+openfaba deobfuscate \
+  --faba-library /mnt/faba/MKI01 \
+  --mp3-library /home/user/output_mp3
+```
+
+## 🪙 Resources used to create this project
+
+- [myfaba-hacks GitHub repository](https://github.com/wansors/myfaba-hacks)
+- [Hacking MyFaba Medium Article](https://medium.com/@wansors/hacking-myfaba-an-educational-journey-into-storytelling-box-customization-cc6fc5db719d)
+- [Myfaba Store](https://www.myfaba.it/prodotti-sonori/acquista-per-tipologia/personaggi-sonori/)
+
+
+## 📦 Tools for Developers
+
+Common development tasks are wrapped in the `Makefile` for convenience.
+
+### Linting, Formatting, and Type Checking
+
+```bash
+make qa
+```
+
+Runs **Ruff** for linting and formatting, and **Mypy** for type checking.
+
+### Running Unit Tests
+
+Before running tests, override any required environment variables in the `.env.test` file.
+
+```bash
+make test
+```
+
+Executes the test suite using **Pytest**.
+
+### Building the Project
+
+```bash
+make build
+```
+
+Generates a distribution package inside the `dist/` directory.
+
+### Cleaning Up
+
+```bash
+make clean
+```
+
+Removes build artifacts, caches, and temporary files to keep your project directory clean.
+
+### Updating project version
+
+```bash
+make version
+```
+
+Interactively prompts you to select the type of version update to apply (major, minor, patch, tag) 
+and automatically updates the project version accordingly.
+
+
+## 🤝 Contributing
+
+Contributions are welcome!
+Please ensure all QA checks and tests pass before opening a pull request.
+
+---
+
+<sub>🚀 Project starter provided by [Cookie Pyrate](https://github.com/gvieralopez/cookie-pyrate)</sub>

openfaba-0.1.2.dist-info/RECORD

@@ -0,0 +1,14 @@
+openfaba/__init__.py,sha256=WTYoljztaWP44HsvOx0CXwehHk1h-iGXA--jZ-edxjo,116
+openfaba/cli.py,sha256=C92hVIFHyFWb0kiUmhg5SbZdXehUMYNkiGRolKmFErc,6223
+openfaba/consts.py,sha256=0VlaEaMw_BSH9Y80kbxxntRXLV5a66zzdossceB8ImM,2290
+openfaba/io.py,sha256=kIipJDVhDbA6ZXxpn7oLT6KxMmERJVnbwi1mWzs2oK0,3400
+openfaba/main.py,sha256=4945JWeFwoSJtjZ76fBxKw7PhssKhwzDKgqEQUc2wos,101
+openfaba/media.py,sha256=fJj2mLN0deAqyWroP70NT1Rtrp-KZtrPjchU1XonYEw,7086
+openfaba/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+openfaba/utils.py,sha256=FMYjsqnjBmy3HcNmr4hfFX7PLDO1iniDR4u84JTOiRw,539
+openfaba-0.1.2.dist-info/licenses/LICENSE,sha256=zTmm46Tbk_vPK5A1X0ZwgBuXysU5fk6Sn_BRYc9nd74,1078
+openfaba-0.1.2.dist-info/METADATA,sha256=vO8DujCZGAbmS-_C5oB3m12qH_6pMfPa4wqdeOQA5f4,6217
+openfaba-0.1.2.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+openfaba-0.1.2.dist-info/entry_points.txt,sha256=9kyUBoAFyDv285_CLuoIIuOA7xGhZc2-nHs7aJxtJ6E,48
+openfaba-0.1.2.dist-info/top_level.txt,sha256=F8kv6M3SNva6WV2r5pgoxGW3V2B1hai8pD9XrOfaByY,9
+openfaba-0.1.2.dist-info/RECORD,,

openfaba-0.1.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

openfaba-0.1.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+openfaba = openfaba.main:main

openfaba-0.1.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gustavo Viera López
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

openfaba-0.1.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+openfaba