openfaba 0.1.2__tar.gz

openfaba-0.1.2/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,218 @@
+# 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/pyproject.toml

@@ -0,0 +1,120 @@
+[project]
+name = "openfaba"
+version = "0.1.2"
+description = "A modern reimplementation of redele."
+readme = "README.md"
+requires-python = ">= 3.13"
+authors = [
+    { name = "Gustavo Viera López", email = "gvieralopez@gmail.com" },
+]
+license = { text = "MIT" }
+
+dependencies = [
+    "typer>=0.9.0",
+    "mutagen>=1.47.0",
+]
+
+[dependency-groups]
+dev = [
+    "bumpver",
+    "mypy",
+    "pytest",
+    "pytest-cov",
+    "pytest-dotenv",
+    "pytest-mock",
+    "ruff",
+]
+
+build = ["build"]
+
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[project.scripts]
+openfaba = "openfaba.main:main"
+
+[tool.ruff]
+line-length = 100
+indent-width = 4
+target-version = "py313"
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+docstring-code-format = true
+docstring-code-line-length = "dynamic"
+
+[tool.ruff.lint]
+select = [
+    "A",      # flake8-builtins: Check variables shadowing
+    "B",      # flake8-bugbear: Finds likely bugs and design problems
+    "C",      # McCabe: Complexity checker to ensure maintainable code
+    "DJ",     # flake8-django: Checks on Django code
+    "E4",     # Pycodestyle: Line length, indentation, etc.
+    "E7",     # Pycodestyle: Miscellaneous checks
+    "E9",     # Pycodestyle: Syntax errors
+    "F",      # Pyflakes: Unused imports, undefined variables, etc.
+    "FIX",    # Avoid lines containing TODO tags
+    "G",      # flake8-logging-format: Ensure logging messages follow best practices.
+    "I",      # Isort: Import sorting
+    "LOG",    # flake8-logging: Use the logging module correctly
+    "N",      # pep8-naming: Enforce naming conventions
+    "PGH004", # Enforce specify the rule to avoid on noqa tags
+    "PTH",    # flake8-use-pathlib: Enforces pathlib usage
+    "RUF",    # Ruff-specific rules: Mostly for handling noqa tags and general stuff
+    "S",      # flake8-bandit: Identifies common security issues in code
+    "T20",    # flake8-print: Avoids print in the code
+]
+ignore = [
+    "S101", # Use of assert function
+    "G004", # F-strings on logging
+    "B008", # Typer Options
+    "C901"
+]
+fixable = ["ALL"]
+unfixable = []
+
+[tool.ruff.lint.per-file-ignores]
+"scripts/**" = ["T20"]  # Allow print statements on the scripts
+
+
+[tool.mypy]
+python_version = "3.13"
+files = ["src", "scripts", "tests"]
+warn_unused_configs = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+strict_equality = true
+check_untyped_defs = true
+disallow_subclassing_any = true
+disallow_untyped_decorators = true
+disallow_any_generics = true
+disallow_untyped_calls = false
+disallow_incomplete_defs = true
+disallow_untyped_defs = true
+no_implicit_reexport = true
+warn_return_any = true
+extra_checks = true
+
+[tool.pytest.ini_options]
+minversion = "6.0"
+addopts = "-ra -q --cov=src --cov-report=term-missing --cov-fail-under=85"
+python_files = "tests.py test_*.py *_test.py"
+pythonpath = "./src"
+env_override_existing_values = 1
+env_files = [".env.test"]
+
+[tool.bumpver]
+current_version = "0.1.2"
+version_pattern = "MAJOR.MINOR.PATCH[-TAGNUM]"
+
+[tool.bumpver.file_patterns]
+"pyproject.toml" = ['^version = "{version}"', '^current_version = "{version}"']
+"src/openfaba/__init__.py" = [
+    '^__version__ = "{version}"$',
+]

openfaba-0.1.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

openfaba-0.1.2/src/openfaba/__init__.py

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