MoodTune

MoodTune is a local-first research prototype for mood journaling, explainable music exploration, and personal audio-library management. Its research interface connects two-dimensional mood input to three social-emotional learning (SEL) labels, while keeping the recommendation logic inspectable.

Implementation boundary: MoodTune is inspired by the SEM Music Dataset and its associated LSEL study. The current application uses transparent rules for exploration; it does not implement or claim the paper's trained LSEL model.

_{Research context, mood input, and explainable music exploration are presented as one coherent workflow.}

What you can explore

• Record happiness and calmness on two continuous axes and review local history.
• Upload MP3, WAV, FLAC, M4A, or OGG audio (maximum 25 MB per file).
• Search and filter a personal media library, then play audio in the browser.
• Receive explainable recommendations tied to Outlook, Problem-Solving, and Empathetic Perspective-Taking.
• Inspect aggregate mood trends and plain-language, non-clinical observations.
• Read the research context, implementation limits, and dataset links in-app.

Research context

The interface is motivated by the peer-reviewed paper:

Y.-J. Lin et al., “LSEL: A lightweight deep learning model for social-emotional classification of classical music,” Machine Learning with Applications, vol. 23, article 100832, 2026. https://doi.org/10.1016/j.mlwa.2025.100832

The public SEM Music Dataset on Kaggle contains 419 source tracks. The paper reports 591 experimental samples in its evaluation pipeline. These are different units and are intentionally presented separately.

Architecture

The diagram separates the interactive experience, application services, and local persistence layers. The paper and dataset inform the SEL taxonomy and research framing; they are deliberately outside the runtime path because this prototype does not execute the trained LSEL model.

SQLite replaces the original external MongoDB dependency so a reviewer can run the complete system without registering for a cloud service. All runtime data is written beneath backend/data/ and backend/uploads/, both excluded from Git.

Run locally

Requirements: Python 3.11+ and Node.js 20+ with Corepack.

1. Start the API

python -m venv .venv
# Windows: .venv\Scripts\activate
# macOS/Linux: source .venv/bin/activate
pip install -r backend/requirements.txt
uvicorn backend.server:app --reload --port 8001

API documentation is available at http://localhost:8001/docs.

2. Start the web client

cd frontend
corepack enable
yarn install --frozen-lockfile
yarn start

Open http://localhost:3000. The defaults require no .env file; optional overrides are documented in each .env.example.

Test and build

python -m pytest -q
cd frontend
yarn build

GitHub Actions repeats both checks on every push and pull request.

API overview

Area	Endpoints
System	GET /health, GET /api/research
Mood journal	POST /api/mood/entry, GET /api/mood/entries, GET /api/mood/analytics, GET /api/mood/insights
Music	POST /api/music/upload, GET /api/music/library, GET /api/music/stream/{id}, DELETE /api/music/{id}
Exploration	GET /api/music/recommendations?happiness=…&calmness=…

Privacy, rights, and limitations

• Mood entries and uploads stay on the machine running the backend by default.
• The prototype has no authentication and should not be exposed directly as a public multi-user service.
• Mood observations are descriptive and are not medical or clinical advice.
• Users are responsible for having permission to upload and play audio files.
• Dataset audio is distributed separately under its own documented rights; no dataset tracks are bundled in this repository.
• Recommendations are deterministic heuristics intended for interface and research-flow exploration, not an evaluation of the LSEL classifier.

See SECURITY.md for responsible reporting guidance.

Project provenance

The initial university prototype was developed with AI-assisted scaffolding. For this open-source release, the application architecture, data layer, interface, tests, security defaults, and research documentation were substantially reviewed and rebuilt. This note is included to keep the development history transparent.

License

Application source code is available under the MIT License. The paper, dataset, and any user-provided music retain their respective rights.