octra-task-0107576c

The user wants the full content of a file named README.md, but the language specified is Python, and the content described is clearly a Python module (music_util.py). The user explicitly says "Write the FULL content of file: README.md" but then describes a Python task and says "Use the standard file extension for python" and "Return the file content as PLAIN TEXT. NO JSON. NO markdown. Just the raw code."

Wait, there's a contradiction: the filename is README.md (Markdown), but the language is Python and the task is to create a Python file. Looking at the task breakdown, it says "Files to Create: music_util.py". However, the user's first line says "Write the FULL content of file: README.md".

I need to resolve this ambiguity. The user might have made a typo in the filename. Given that:

1. The language is specified as Python
2. The task is to implement a Python utility music_util.py
3. The user says "Use the standard file extension for python"
4. The user says "Return the file content as PLAIN TEXT... Just the raw code"

It seems the user likely meant to ask for the content of music_util.py, not README.md. However, they explicitly wrote "Write the FULL content of file: README.md".

But wait - could they want a README.md file that contains the Python code? That would be bizarre. Or do they want me to write the python code for music_util.py and just ignore the filename discrepancy?

Given the strong constraints ("Language: python", "Write COMPLETE python code", "standard file extension for python", "Return the file content as PLAIN TEXT... Just the raw code"), I should provide the Python code for music_util.py. The mention of README.md in the first line is likely a template artifact or mistake. The actual task content clearly defines music_util.py as the file to create.

Actually, re-reading carefully: "Write the FULL content of file: README.md" might be a system prompt template where the user forgot to change the filename. But the task breakdown explicitly says create music_util.py.

Given the instruction "Use the standard file extension for python" and "Just the raw code", I should output the raw Python code for music_util.py. The filename in the first line is likely an error in the prompt. I will provide the Python file content as requested.

Let me design the code:

Requirements:

1. Single file: music_util.py
2. CLI parsing with argparse: commands play, stop, scan, list, plus positional args for file paths/directories. Help text and input validation.
3. Audio library handling: recursive scan for MP3, FLAC, OGG, WAV. In-memory index mapping track identifiers to file paths and basic metadata.
4. Music playback: pygame backend. Initialize, load tracks by path or index, transport controls (play, pause, resume, stop). Playback state management. Resource release on exit.
5. Python 3.10+
6. Standalone entry point + main(argv=None) for programmatic use.

Implementation plan:

• Imports: argparse, os, sys, pathlib, typing, atexit, json (maybe not needed), mutagen? Wait, the task says single-file utility interface. It doesn't mention mutagen as a dependency. It only mentions pygame as strictly required. So for metadata, I might need to extract basic metadata without external libs, or just use file stats if mutagen isn't available. But maybe I should try to use mutagen if available? No, the dependencies only list Python 3.10+ and pygame. I should not assume mutagen is installed. I can use os.path and basic filename parsing for metadata. Or try mutagen optionally, but the prompt says "strictly required: pygame". It doesn't forbid other deps but says standalone. To be safe, I should avoid extra dependencies beyond pygame. I'll use filename and pathlib for basic metadata (e.g., title from filename).

Wait, for MP3 metadata without mutagen, it's hard. But the task says "basic metadata". I can provide filename, size, and maybe duration if pygame can provide it? Pygame mixer can get length? pygame.mixer.Sound(file) can get length via get_length(). That requires loading the file. For scanning, loading every file into pygame just to get length might be slow and resource-intensive. But it's a simple utility.

Actually, the task says "basic metadata". I can store: file path, filename (as title), format (extension), size. If we want duration, we can load via pygame.mixer.Sound during scan, but that might fail for some files or be slow. Alternatively, we can just skip duration or compute it lazily.

Let's structure the code:

1. AudioLibrary class:

   • __init__
   • scan(paths) - recursive scan for .mp3, .flac, .ogg, .wav
   • add_track(path) - add to index
   • get_track(identifier) - identifier can be integer index or string path? The task says "mapping track identifiers to file paths". I'll use integer IDs displayed in list, and also allow lookup by exact path.
   • list_tracks() - return formatted list
   • _get_metadata(path) - returns dict with basic info

2. PlaybackController class:

   • __init__
   • initialize() - pygame.mixer.init()
   • load(track_info) - load Sound object
   • play(path_or_id) - load and play
   • pause()
   • resume()
   • stop()
   • is_playing(), is_paused()
   • close() / __del__ - quit mixer, release resources

3. CLI class or functions:

   • build_parser() - argparse
   • main(argv=None) - main entry point
   • commands: play, stop, scan, list

Wait, the task says "Implement a command-line interface using Python's built-in argparse to accept commands (e.g., play, stop, scan, list) and positional arguments for file paths or directories."

So likely:

python music_util.py play /path/to/song.mp3
python music_util.py scan /path/to/music
python music_util.py list
python music_util.py stop

But how does state persist between commands? Since it's a CLI tool invoked per command, playback started in one process won't be accessible from another unless we daemonize. But the task says "standalone entry point". It mentions playback state managed cleanly and resources released on exit.

If it's invoked as python music_util.py play, it will play and block? Or play and exit? Usually a simple CLI player might play and wait. Let's make it so that play starts playback and blocks until finished (or until interrupted), stop might not make sense in a single invocation unless we use some IPC or pid file. But the task explicitly mentions stop command.

Hmm. To support stop, we could either:

• Make the process daemonize/background itself on play, and stop finds the PID? That seems overly complex for this prompt.
• Or, structure it as an interactive/daemon mode? But the task says CLI commands.
• Or, support stop only when the user hits Ctrl+C? No, task explicitly lists stop.

Wait, maybe the intended design is that the user runs python music_util.py play ... and it blocks, and stop is handled inside the application via a separate thread listening for input? Or maybe stop is not a subcommand but an interactive command? No, task says commands.

Alternative: The tool could be a persistent REPL-like CLI, but the task says argparse commands.

Another interpretation: The main() function is called programmatically. When called with argv=['play', ...], it plays. When called with argv=['stop'], it stops. This implies the PlaybackController lives as long as the Python process. So if a wrapper imports main and calls main(['play', ...]), then later main(['stop']), they share the module-level state. That's actually a good approach! Use module-level singletons for library and playback controller. Then main() can be imported and invoked multiple times within the same process. This aligns with "integration with potential wrapper modules".

So I'll design with module-level singleton instances:

_library = AudioLibrary()
_player = PlaybackController()

And main(argv) uses these singletons.

Let's detail argparse:

parser = argparse.ArgumentParser(description="Music Playback Utility")
subparsers = parser.add_subparsers(dest='command')

play_parser = subparsers.add_parser('play', help='Play a track by path or index')
play_parser.add_argument('target', help='File path or track index to play')

stop_parser = subparsers.add_parser('stop', help='Stop playback')

scan_parser = subparsers.add_parser('scan', help='Scan directories for audio files')
scan_parser.add_argument('directories', nargs='+', help='Directories to scan')

list_parser = subparsers.add_parser('list', help='List indexed tracks')