Simple DjIA v0.1: human-centered open-platform music engine

.github/workflows/python-app.yml

@@ -1,22 +1,26 @@
-# This workflow will install Python dependencies, run tests and lint with a single version of Python
-# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python
-
+# Legacy PythonProjects workflow. SimpleDjIA has its own isolated compatibility matrix.
 name: Python application
 
 on:
   push:
     branches: [ "master" ]
+    paths-ignore:
+      - 'SimpleDjIA/**'
+      - '.github/workflows/simple-djia.yml'
+      - '.github/workflows/python-app.yml'
   pull_request:
     branches: [ "master" ]
+    paths-ignore:
+      - 'SimpleDjIA/**'
+      - '.github/workflows/simple-djia.yml'
+      - '.github/workflows/python-app.yml'
 
 permissions:
   contents: read
 
 jobs:
   build:
-
     runs-on: ubuntu-latest
-
     steps:
     - uses: actions/checkout@v4
     - name: Set up Python 3.10
@@ -30,10 +34,7 @@ jobs:
         if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
     - name: Lint with flake8
       run: |
-        # stop the build if there are Python syntax errors or undefined names
         flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
-        # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
         flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
     - name: Test with pytest
-      run: |
-        pytest
+      run: pytest

.github/workflows/simple-djia.yml

@@ -0,0 +1,49 @@
+name: Simple DjIA
+
+on:
+  push:
+    branches: [master, feature/simple-djia-v1]
+    paths:
+      - 'SimpleDjIA/**'
+      - '.github/workflows/simple-djia.yml'
+  pull_request:
+    branches: [master]
+    paths:
+      - 'SimpleDjIA/**'
+      - '.github/workflows/simple-djia.yml'
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.10', '3.11', '3.12', '3.13']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Show runtime
+        run: |
+          python --version
+          python -c "import sys; print(sys.platform); print(sys.executable)"
+      - name: Compile source
+        working-directory: SimpleDjIA
+        run: python -m compileall -q src
+      - name: Install test dependency
+        run: python -m pip install pytest
+      - name: Run tests without packaging
+        working-directory: SimpleDjIA
+        env:
+          PYTHONPATH: src
+        run: python -m pytest -q
+      - name: Install package
+        working-directory: SimpleDjIA
+        run: python -m pip install -e .
+      - name: Smoke CLI
+        working-directory: SimpleDjIA
+        run: simple-djia --help

SimpleDjIA/COMPATIBILITY.md

@@ -0,0 +1,59 @@
+# Simple DjIA compatibility report
+
+Validation performed during the v0.1 development pass.
+
+## Local Linux validation
+
+Environment used by the development runner:
+
+- Linux
+- CPython 3.13.5
+- Tk 8.6 available
+- pytest 9.0.2
+- ffplay available as an open playback backend
+
+Results:
+
+- `python -m compileall -q src`: PASS
+- unit tests: **9 passed**
+- CLI smoke test (`python -m simple_djia.cli --help`): PASS
+- Tkinter/GUI module import: PASS
+- player discovery: PASS; ffplay detected in the validation environment
+- editable installation: PASS when build isolation is disabled in the network-isolated development runner (`pip --no-build-isolation -e .`)
+
+The normal install documented in the README remains `pip install -e .`; it requires access to Python package infrastructure only to satisfy the standard build backend requirement if it is not already installed.
+
+## Python grammar compatibility
+
+Every Python source file was parsed using CPython's versioned grammar compatibility mode for:
+
+- Python 3.10: PASS
+- Python 3.11: PASS
+- Python 3.12: PASS
+- Python 3.13: PASS
+
+The application intentionally uses only standard-library runtime APIs that are available across this range.
+
+## GitHub Actions
+
+A dedicated Ubuntu matrix is committed for Python 3.10, 3.11, 3.12 and 3.13. During this development session, GitHub created all four jobs but reported each as failed before exposing any executed steps or job log blob. Because the jobs did not reach a visible test step, this cannot be treated as a source-code test failure. The workflow remains in the repository so it can execute normally when GitHub-hosted runners are available for the account/repository.
+
+The legacy root `Python application` workflow is isolated from SimpleDjIA-only changes to avoid collecting unrelated historical experiments in this subproject's validation.
+
+## Playback compatibility
+
+Simple DjIA does not embed a proprietary audio engine. It discovers, in order:
+
+1. MPV (`mpv`)
+2. VLC (`cvlc`)
+3. FFmpeg player (`ffplay`)
+
+Actual codec support therefore follows the selected backend. OGG/Vorbis, FLAC and WAV are recommended for an open workflow.
+
+## Known v0.1 limits
+
+- audio features are human-supplied metadata; automatic feature extraction is a later enhancement;
+- no crossfade/mixing engine yet;
+- GUI playback is intentionally simple: selected track, next track and stop;
+- no streaming-service or DRM integration by design;
+- wellbeing-oriented profiles are contextual curation tools and are not clinical music therapy.

SimpleDjIA/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sidiney Rodrigues
+
+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.

SimpleDjIA/README.md

@@ -0,0 +1,183 @@
+# Simple DjIA
+
+**Simple DjIA** is an open-source, human-centered music programming application for Linux and other open platforms. It behaves like a contextual musician: a discreet pianist in a restaurant, an energetic DJ at a party, a calm background selector, or a focus-oriented ambient curator.
+
+The project deliberately keeps musical decisions transparent. It does **not** claim to replace a human DJ, musician, therapist, or clinical music therapist. Its wellbeing-oriented profiles are inspired by human listening, context, familiarity, gradual change, and respect for the people in the room.
+
+## Philosophy
+
+A playlist is not just a ranking problem. Human listeners notice repetition, sudden changes, excessive volume/energy, intrusive vocals, familiarity, silence, and the social function of a place. Simple DjIA therefore uses explicit criteria rather than a hidden recommendation model.
+
+Each track can carry human-readable metadata:
+
+- tempo/BPM
+- energy
+- valence (pleasant/positive affect proxy)
+- acousticness
+- danceability
+- vocal presence
+- familiarity
+- tags such as `piano`, `instrumental`, `house`, `ambient`, `bossa`
+
+Each behavior profile describes a desired musical environment and the selector explains why tracks fit it.
+
+## Included behaviors
+
+- `restaurant_piano` — discreet piano/acoustic background for conversation
+- `mega_party_dj` — high-energy dance-oriented sequencing
+- `calm_connection` — gentle, low-overload listening inspired by human connection
+- `focus_background` — restrained instrumental background with low vocal presence
+
+Profiles live in `src/simple_djia/profiles.py`, so interested users can copy, inspect, modify, or create their own.
+
+## Open-platform design
+
+The Python core uses only the standard library. Audio playback is delegated to established open tools, detected in this order:
+
+1. `mpv`
+2. `cvlc` (VLC)
+3. `ffplay` (FFmpeg)
+
+This avoids binding the application to proprietary codecs, stores, streaming APIs, DRM, or closed operating-system frameworks. OGG, FLAC, WAV and other formats supported by the installed player are recommended. Users are responsible for the rights to music they add.
+
+## Requirements
+
+- Python 3.10+
+- Linux recommended
+- Tk/Tkinter for the desktop interface
+- optional playback backend: MPV, VLC, or FFmpeg
+
+Debian/Ubuntu example:
+
+```bash
+sudo apt install python3 python3-tk mpv
+```
+
+Fedora example:
+
+```bash
+sudo dnf install python3 python3-tkinter mpv
+```
+
+Arch Linux example:
+
+```bash
+sudo pacman -S python tk mpv
+```
+
+## Install
+
+From the `SimpleDjIA` directory:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+pip install -e .
+```
+
+No runtime Python dependencies beyond the standard library are required.
+
+## Create a library
+
+Copy `examples/library.example.json` and point each entry to audio that you are legally allowed to play. Relative paths are resolved from the JSON file location.
+
+Example:
+
+```json
+{
+  "path": "./music/song.ogg",
+  "title": "Song",
+  "artist": "Artist",
+  "genre": "piano",
+  "bpm": 82,
+  "energy": 0.30,
+  "valence": 0.60,
+  "acousticness": 0.90,
+  "danceability": 0.20,
+  "vocal_presence": 0.00,
+  "familiarity": 0.50,
+  "tags": ["piano", "instrumental"]
+}
+```
+
+All normalized values use the range `0.0` to `1.0`.
+
+## Command line
+
+Preview a restaurant playlist:
+
+```bash
+simple-djia examples/library.example.json --scene restaurant_piano --limit 12
+```
+
+Build and play a party session:
+
+```bash
+simple-djia examples/library.example.json --scene mega_party_dj --limit 25 --play
+```
+
+## Desktop menu
+
+```bash
+simple-djia-gui
+```
+
+Choose a JSON library, select the desired behavior, choose playlist length, then generate the ordered playlist.
+
+## How selection works
+
+1. Tracks carrying explicitly avoided tags are removed.
+2. Vocal-density limits are respected for contexts where speech/conversation matters.
+3. BPM is compared with the scene's target and tolerance.
+4. Human-readable features are compared with scene targets using explicit weights.
+5. Preferred tags add a small bonus.
+6. The resulting candidates are re-ordered to reduce abrupt BPM/energy/valence changes.
+7. Consecutive tracks by the same artist are avoided when a reasonable alternative exists.
+
+There is no opaque model deciding what a person is supposed to feel. The scoring rules are ordinary Python and can be inspected or changed.
+
+## Testing and compatibility
+
+Run locally:
+
+```bash
+pip install pytest
+pytest -q
+python -m compileall -q src
+simple-djia --help
+```
+
+The repository includes a GitHub Actions matrix for Python 3.10, 3.11, 3.12 and 3.13 on Ubuntu Linux.
+
+## Project layout
+
+```text
+SimpleDjIA/
+├── pyproject.toml
+├── README.md
+├── LICENSE
+├── examples/
+│   └── library.example.json
+├── src/simple_djia/
+│   ├── cli.py
+│   ├── gui.py
+│   ├── library.py
+│   ├── models.py
+│   ├── player.py
+│   ├── profiles.py
+│   ├── selector.py
+│   └── session.py
+└── tests/
+    ├── test_library.py
+    ├── test_models.py
+    └── test_selector.py
+```
+
+## Roadmap
+
+The first release intentionally favors understandable rules over hype. Useful later additions include manual feedback controls (`more calm`, `more dance`, `less vocal`), local audio-feature extraction, MIDI/live-piano generation using the existing Python Music Composer work, crossfades via MPV IPC, room/session history stored locally, and optional local-only machine learning whose recommendations remain explainable and user-overridable.
+
+## License
+
+MIT. See `LICENSE`.

SimpleDjIA/examples/library.example.json

@@ -0,0 +1,30 @@
+[
+  {
+    "path": "./music/restaurant-piano-01.ogg",
+    "title": "Mesa perto da janela",
+    "artist": "Example Artist",
+    "genre": "piano",
+    "bpm": 78,
+    "energy": 0.24,
+    "valence": 0.62,
+    "acousticness": 0.95,
+    "danceability": 0.18,
+    "vocal_presence": 0.0,
+    "familiarity": 0.45,
+    "tags": ["piano", "instrumental", "acoustic"]
+  },
+  {
+    "path": "./music/party-house-01.ogg",
+    "title": "Open Floor",
+    "artist": "Example DJ",
+    "genre": "house",
+    "bpm": 126,
+    "energy": 0.9,
+    "valence": 0.82,
+    "acousticness": 0.08,
+    "danceability": 0.94,
+    "vocal_presence": 0.32,
+    "familiarity": 0.65,
+    "tags": ["dance", "house", "electronic", "party"]
+  }
+]