<!--
SPDX-FileCopyrightText: 2024 Max Mehl <https://mehl.mx>
SPDX-License-Identifier: GPL-3.0-only
-->
# Tonuino Cards Manager
[](https://github.com/mxmehl/tonuino-cards-manager/actions/workflows/test.yaml)
[](https://api.reuse.software/info/github.com/mxmehl/tonuino-cards-manager)
[](https://pypi.org/project/tonuino-cards-manager/)
[](https://pypi.org/project/tonuino-cards-manager/)
Welcome to the **Tonuino Cards Manager**, a convenient utility designed to streamline the process of managing and organizing music for [Tonuino music boxes](https://www.voss.earth/tonuino/). This tool simplifies managing your Tonuino's SD card content and RFID cards settings.
## Table of Contents
- [Overview](#overview)
- [Features](#features)
- [Installation](#installation)
- [Usage](#usage)
- [Demo](#demo)
- [Configuration](#configuration)
- [Limitations](#limitations)
- [Contributing](#contributing)
- [License](#license)
## Overview
The **Tonuino Cards Manager** provides an easy way to prepare and manage music collections for your Tonuino music box. Whether you want to assign single songs or entire albums to specific RFID cards, this tool handles the setup seamlessly through a single YAML configuration file.
## Features
- **Easy Configuration**: Use a simple YAML file to define which music plays for each RFID card.
- **Multiple Sources**: Assign songs or albums from various sources to one RFID card.
- **All modi**: The tool supports all modern playing modi, e.g. single and party mode.
- **Automated Management**: The tool automates the copying and organizing of music files into the appropriate structure for Tonuino.
- **QR Code Generation**: QR codes will be generated for each card which allows you to quickly configure your cards, e.g. with [TonUINO NFC Tools](https://marc136.github.io/tonuino-nfc-tools/)
- **User-Friendly**: Intuitive and designed with simplicity in mind for managing kids' music collections.
## Installation
To install the **Tonuino Cards Manager**, you need to have Python (at least version 3.10) installed. You can install the application using `pip`:
```
pip3 install tonuino-cards-manager
```
## Usage
Once installed, you can use the tool by following these steps:
1. Prepare your YAML configuration file (e.g. `mybox.yaml`), specifying the music for each RFID card.
2. Run the tool with the following command:
```bash
tonuino-cards-manager --config mybox.yaml --destination /path/to/tonuino-sd-card/
```
3. The tool will process the YAML file and organize your music according to the specified configuration (see below).
Check out `tonuino-cards-manager --help` for all available options.
### Demo
[](https://asciinema.org/a/663963)
The resulting QR code(s) can be scanned with [TonUINO NFC Tools](https://marc136.github.io/tonuino-nfc-tools/). There, you can press on "Enter list" and "Read QR code", and thereby program your RFID cards in batch.
## Configuration
The core of the **Tonuino Cards Manager** is the configuration file where you define your music setup. Here's a basic example of what the configuration might look like:
```yaml
# sourcebasedir: ""
# cardcookie: "1337B347"
# version: 2
cards:
# A whole directory in album mode
1:
source:
- Rolf Zuckowski/1994 Im Kindergarten
mode: album
# A whole directory in party mode. A single source can also be written this way
2:
source: Fredrik Vahle/1990 Der Spatz
mode: party
# A whole directory, play one of the 10 first episodes randomly
3:
source: Audio Books/Benjamin Blümchen/
mode: play-from-to
from_song: 1
to_song: 10
# Multiple single songs and a whole directory in party mode
4:
description: Favourite songs of the last few weeks
source:
- Singles/Die alte Moorhexe.mp3
- Singles/Große Uhren machen tick tack.mp3
- Singles/Best of Last Vacation/
mode: party
```
### Configuration Details
- **sourcebasedir**: If all your music is in one directory, you can add the path here and make the `source` entries for the cards relative to this directory. Default: `""`
- **cardcookie**: The card cookie of your Tonuino box. [Background here](https://discourse.voss.earth/t/bedeutung-der-konstante-cardcookie/10241). Default: `1337B347`
- **version**: Card format version, `2` for Tonuino 2.1.x and TNG. Default: `2`
- **cards**: A list of RFID cards.
- **id**: The number of the card. These numbers must be unique and be actual numbers, not texts.
- **description**: A free-text field to describe the card, useful for collections of single songs. Only relevant for your information when handling the QR code. Default: `""`
- **source**: A string or list of paths to songs or albums assigned to the card. Mandatory.
- **mode**: The play mode for this card. Can be any of the following modes. Default: `play-random`
- `play-random`: play a random file from the folder, front-back buttons locked
- `album`: play the complete folder
- `party`: play files in the folder in random order
- `single`: play a specific file in the folder
- `audiobook`: play a folder and save the progress
- `admin`: create an admin card
- `play-from-to`: play a random file between the start and end file (you need to set `from_song` and `to_song`)
- `album-from-to`: play all files between the start and end file in consecutive order (you need to set `from_song` and `to_song`)
- `party-from-to`: play all files between the start and end file at random (you need to set `from_song` and `to_song`)
- **from_song**: If you set one of the `*-from-to` modes, write the number of the song you want to start from (from the list of sources you provided). Default: `0`
- **to_song**: Equivalent to `from_song`. Default: `0`
## Limitations
The tool currently has a few limitation. Please feel free to contribute to the project or share your ideas how to fix them.
- A maximum of 99 cards will be supported as every configured card will create a separate folder. A typical Tonuino's MP3 player component can only support folders between 01-99.
- Version 1 of the RFID cards format is not tested as I don't have such a box.
## Contributing
Contributions are welcome! To contribute to the **Tonuino Cards Manager**, please check out the [Contribution guide](CONTRIBUTING.md).
## License
This project is licensed under the GNU General Public License v3.0 (GPL-3.0-only). See the [LICENSE](LICENSE) file for details.
There may be components under different, but compatible licenses and from different copyright holders. The project is [REUSE](https://reuse.software/) compliant which makes these portions transparent. You will find all used licenses in the [LICENSES](LICENSES/) directory.
---
Happy listening with your Tonuino music box! If you have any questions or need further assistance, please open an issue on GitHub.
Raw data
{
"_id": null,
"home_page": "https://github.com/mxmehl/tonuino-cards-manager",
"name": "tonuino-cards-manager",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": "tonuino, management, automation",
"author": "Max Mehl",
"author_email": "mail@mehl.mx",
"download_url": "https://files.pythonhosted.org/packages/86/5e/c25369ca50d0592d9e35e88b52cd653a48d0b30101a78575b9f236f1d363/tonuino_cards_manager-0.1.2.tar.gz",
"platform": null,
"description": "<!--\nSPDX-FileCopyrightText: 2024 Max Mehl <https://mehl.mx>\n\nSPDX-License-Identifier: GPL-3.0-only\n-->\n\n# Tonuino Cards Manager\n\n[](https://github.com/mxmehl/tonuino-cards-manager/actions/workflows/test.yaml)\n[](https://api.reuse.software/info/github.com/mxmehl/tonuino-cards-manager)\n[](https://pypi.org/project/tonuino-cards-manager/)\n[](https://pypi.org/project/tonuino-cards-manager/)\n\nWelcome to the **Tonuino Cards Manager**, a convenient utility designed to streamline the process of managing and organizing music for [Tonuino music boxes](https://www.voss.earth/tonuino/). This tool simplifies managing your Tonuino's SD card content and RFID cards settings.\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Features](#features)\n- [Installation](#installation)\n- [Usage](#usage)\n - [Demo](#demo)\n- [Configuration](#configuration)\n- [Limitations](#limitations)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Overview\n\nThe **Tonuino Cards Manager** provides an easy way to prepare and manage music collections for your Tonuino music box. Whether you want to assign single songs or entire albums to specific RFID cards, this tool handles the setup seamlessly through a single YAML configuration file.\n\n## Features\n\n- **Easy Configuration**: Use a simple YAML file to define which music plays for each RFID card.\n- **Multiple Sources**: Assign songs or albums from various sources to one RFID card.\n- **All modi**: The tool supports all modern playing modi, e.g. single and party mode.\n- **Automated Management**: The tool automates the copying and organizing of music files into the appropriate structure for Tonuino.\n- **QR Code Generation**: QR codes will be generated for each card which allows you to quickly configure your cards, e.g. with [TonUINO NFC Tools](https://marc136.github.io/tonuino-nfc-tools/)\n- **User-Friendly**: Intuitive and designed with simplicity in mind for managing kids' music collections.\n\n## Installation\n\nTo install the **Tonuino Cards Manager**, you need to have Python (at least version 3.10) installed. You can install the application using `pip`:\n\n```\npip3 install tonuino-cards-manager\n```\n\n## Usage\n\nOnce installed, you can use the tool by following these steps:\n\n1. Prepare your YAML configuration file (e.g. `mybox.yaml`), specifying the music for each RFID card.\n2. Run the tool with the following command:\n ```bash\n tonuino-cards-manager --config mybox.yaml --destination /path/to/tonuino-sd-card/\n ```\n3. The tool will process the YAML file and organize your music according to the specified configuration (see below).\n\nCheck out `tonuino-cards-manager --help` for all available options.\n\n### Demo\n\n[](https://asciinema.org/a/663963)\n\nThe resulting QR code(s) can be scanned with [TonUINO NFC Tools](https://marc136.github.io/tonuino-nfc-tools/). There, you can press on \"Enter list\" and \"Read QR code\", and thereby program your RFID cards in batch.\n\n## Configuration\n\nThe core of the **Tonuino Cards Manager** is the configuration file where you define your music setup. Here's a basic example of what the configuration might look like:\n\n```yaml\n# sourcebasedir: \"\"\n# cardcookie: \"1337B347\"\n# version: 2\n\ncards:\n # A whole directory in album mode\n 1:\n source:\n - Rolf Zuckowski/1994 Im Kindergarten\n mode: album\n # A whole directory in party mode. A single source can also be written this way\n 2:\n source: Fredrik Vahle/1990 Der Spatz\n mode: party\n # A whole directory, play one of the 10 first episodes randomly\n 3:\n source: Audio Books/Benjamin Bl\u00fcmchen/\n mode: play-from-to\n from_song: 1\n to_song: 10\n # Multiple single songs and a whole directory in party mode\n 4:\n description: Favourite songs of the last few weeks\n source:\n - Singles/Die alte Moorhexe.mp3\n - Singles/Gro\u00dfe Uhren machen tick tack.mp3\n - Singles/Best of Last Vacation/\n mode: party\n```\n\n### Configuration Details\n\n- **sourcebasedir**: If all your music is in one directory, you can add the path here and make the `source` entries for the cards relative to this directory. Default: `\"\"`\n- **cardcookie**: The card cookie of your Tonuino box. [Background here](https://discourse.voss.earth/t/bedeutung-der-konstante-cardcookie/10241). Default: `1337B347`\n- **version**: Card format version, `2` for Tonuino 2.1.x and TNG. Default: `2`\n- **cards**: A list of RFID cards.\n - **id**: The number of the card. These numbers must be unique and be actual numbers, not texts.\n - **description**: A free-text field to describe the card, useful for collections of single songs. Only relevant for your information when handling the QR code. Default: `\"\"`\n - **source**: A string or list of paths to songs or albums assigned to the card. Mandatory.\n - **mode**: The play mode for this card. Can be any of the following modes. Default: `play-random`\n - `play-random`: play a random file from the folder, front-back buttons locked\n - `album`: play the complete folder\n - `party`: play files in the folder in random order\n - `single`: play a specific file in the folder\n - `audiobook`: play a folder and save the progress\n - `admin`: create an admin card\n - `play-from-to`: play a random file between the start and end file (you need to set `from_song` and `to_song`)\n - `album-from-to`: play all files between the start and end file in consecutive order (you need to set `from_song` and `to_song`)\n - `party-from-to`: play all files between the start and end file at random (you need to set `from_song` and `to_song`)\n - **from_song**: If you set one of the `*-from-to` modes, write the number of the song you want to start from (from the list of sources you provided). Default: `0`\n - **to_song**: Equivalent to `from_song`. Default: `0`\n\n## Limitations\n\nThe tool currently has a few limitation. Please feel free to contribute to the project or share your ideas how to fix them.\n\n- A maximum of 99 cards will be supported as every configured card will create a separate folder. A typical Tonuino's MP3 player component can only support folders between 01-99.\n- Version 1 of the RFID cards format is not tested as I don't have such a box.\n\n## Contributing\n\nContributions are welcome! To contribute to the **Tonuino Cards Manager**, please check out the [Contribution guide](CONTRIBUTING.md).\n\n## License\n\nThis project is licensed under the GNU General Public License v3.0 (GPL-3.0-only). See the [LICENSE](LICENSE) file for details.\n\nThere may be components under different, but compatible licenses and from different copyright holders. The project is [REUSE](https://reuse.software/) compliant which makes these portions transparent. You will find all used licenses in the [LICENSES](LICENSES/) directory.\n\n---\n\nHappy listening with your Tonuino music box! If you have any questions or need further assistance, please open an issue on GitHub.\n",
"bugtrack_url": null,
"license": "GPL-3.0-only",
"summary": "Manage Tonuino RFID and SD cards by one configuration file. Easy, lightweight and feature-rich",
"version": "0.1.2",
"project_urls": {
"Homepage": "https://github.com/mxmehl/tonuino-cards-manager",
"Repository": "https://github.com/mxmehl/tonuino-cards-manager"
},
"split_keywords": [
"tonuino",
" management",
" automation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6df1431f61a7652acac9280f289ed113ce215ee616c4231df4738ae631f2e385",
"md5": "3e2b701dd24eb1341e275a8733786101",
"sha256": "f1568736f6f998915b7ca710bbef123e5b9e62db7d6628f06177fb3cbbeffd6f"
},
"downloads": -1,
"filename": "tonuino_cards_manager-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3e2b701dd24eb1341e275a8733786101",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 46104,
"upload_time": "2024-06-16T20:48:30",
"upload_time_iso_8601": "2024-06-16T20:48:30.753394Z",
"url": "https://files.pythonhosted.org/packages/6d/f1/431f61a7652acac9280f289ed113ce215ee616c4231df4738ae631f2e385/tonuino_cards_manager-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "865ec25369ca50d0592d9e35e88b52cd653a48d0b30101a78575b9f236f1d363",
"md5": "ebc5e9ca2d4aea6842717a0b2ab2c8fc",
"sha256": "ef5772449949b4a9bddeace78dc1879c28faf8b1b9d5a941367864d48db78618"
},
"downloads": -1,
"filename": "tonuino_cards_manager-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "ebc5e9ca2d4aea6842717a0b2ab2c8fc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 42584,
"upload_time": "2024-06-16T20:48:31",
"upload_time_iso_8601": "2024-06-16T20:48:31.952800Z",
"url": "https://files.pythonhosted.org/packages/86/5e/c25369ca50d0592d9e35e88b52cd653a48d0b30101a78575b9f236f1d363/tonuino_cards_manager-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-16 20:48:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mxmehl",
"github_project": "tonuino-cards-manager",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "tonuino-cards-manager"
}
JSON
