{"id":23190650,"url":"https://github.com/mlang/llm-mpd","last_synced_at":"2025-08-18T19:32:00.218Z","repository":{"id":219352548,"uuid":"744397532","full_name":"mlang/tracktales","owner":"mlang","description":"MPD presenter using OpenAI Chat Completions and TTS","archived":false,"fork":false,"pushed_at":"2024-01-31T07:33:58.000Z","size":13,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-08-14T00:30:28.679Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mlang.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2024-01-17T08:07:49.000Z","updated_at":"2024-03-22T11:35:00.000Z","dependencies_parsed_at":"2024-01-29T13:46:41.778Z","dependency_job_id":null,"html_url":"https://github.com/mlang/tracktales","commit_stats":null,"previous_names":["mlang/tracktales"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlang%2Ftracktales","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlang%2Ftracktales/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlang%2Ftracktales/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlang%2Ftracktales/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mlang","download_url":"https://codeload.github.com/mlang/tracktales/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230268715,"owners_count":18199806,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-18T12:15:09.977Z","updated_at":"2025-08-18T19:32:00.194Z","avatar_url":"https://github.com/mlang.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# llm-mpd\n\n\u003e Narrator for Music Player Daemon (MPD)\n\n`llm-mpd` collects details about the current and upcoming tracks, sends them to an LLM to craft a spoken introduction, synthesizes the narration with OpenAI TTS, and inserts the resulting audio clip into your MPD playlist so it plays between songs.\n\n## Features\n- Automatically generated, voice-acted narrations between tracks  \n- Vision support: album-art descriptions incorporated into the script  \n- Works with MPD random mode and adds padding to accommodate crossfade\n- Tool calling (e.g. local weather) for timely shout-outs  \n- Fully configurable through [LLM templates](https://llm.datasette.io/en/stable/templates.html) and CLI flags\n\n## Installation\n\nPrerequisites  \n* Python ≥ 3.9  \n* Running MPD server with write access to its `music_directory`  \n* `ffmpeg` available on your `$PATH`  \n* OpenAI API key (for TTS)\n\n```bash\n# Install the core LLM framework\npipx install llm\n\n# Install this plugin\nllm install git+https://github.com/mlang/llm-mpd\n```\n\n## Setup\n\n1. Create a writable sub-directory inside your MPD music directory, for example:  \n   ```bash\n   mkdir -p /music/openai-speech\n   chown mpd:mpd /music/openai-speech   # adjust user/group if needed\n   ```\n2. Set your OpenAI key (or pass it with `--tts-api-key`):  \n   ```bash\n   llm keys set openai\n   ```\n\n## Usage\n\nStart the narrator:\n\n```bash\nllm mpd --clips-directory openai-speech\n```\n\nCommon options:\n\n| Flag | Default | Purpose |\n|------|---------|---------|\n| `--template` | `mpd:default` | Select an LLM template |\n| `--param KEY VALUE` | – | Override template variables |\n| `--tool` | – | Expose an LLM tool (e.g. weather) |\n| `--tts-model` | `gpt-4o-mini-tts` | OpenAI TTS model |\n| `--always` | off | Announce every song, not just those with art |\n\nRun `llm mpd --help` for the full list.\n\n## Customisation\n\nTemplates live in the LLM template system.  \nThe bundled `mpd:default` template supports:\n\n| Parameter | Default | Description |\n|-----------|---------|-------------|\n| `name`    | Nova    | On-air persona |\n| `station` | Radio Mario | Station name |\n| `location`| Graz    | Listener city |\n| `region`  | Austria | Listener region |\n| `language`| Austrian German | Language to speak |\n\nOverride any of these:\n\n```bash\nllm mpd \\\n  --clips-directory openai-speech \\\n  --param name DJ-Wanda \\\n  --param language \"Canadian French\"\n```\n\n## Suggested Plugins\n\nEnable weather references in narrations:\n\n```bash\nllm install git+https://github.com/mlang/llm-sky\nllm mpd --tool 'Local(\"Graz\")' --clips-directory openai-speech\n```\n\n## Contributing\n\nIssues and pull requests are welcome.  \n\n## License\n\nApache-2.0 – see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmlang%2Fllm-mpd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmlang%2Fllm-mpd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmlang%2Fllm-mpd/lists"}