A sophisticated interactive music player built on MOC (Music on Console)
and the `chloop <https://github.com/kenjyco/chloop>`__ REPL framework
that transforms audio listening into an intelligent, annotated
experience. This library provides vim-style keyboard controls, timestamp
marking, and persistent comment storage to help users deeply engage with
audio content.
The core philosophy centers on **active listening workflows** where
users can mark interesting moments, add contextual notes, and build
searchable audio archives over time. Whether analyzing podcasts,
studying music, reviewing recordings, or conducting audio research,
mocp-cli reduces the mental overhead of navigating complex audio files
by making annotation and navigation effortless.
The library integrates seamlessly with Redis-based data storage and the
broader helper library ecosystem, enabling powerful audio workflow
automation and cross-session persistence.
Install
-------
Install the actual `MOC player/server <https://moc.daper.net/>`__
::
sudo apt-get install -y moc
or
::
brew install moc
If you **don’t
have**\ `docker <https://docs.docker.com/get-docker>`__\ **installed**,
install Redis and start server
::
sudo apt-get install -y redis-server
or
::
brew install redis
brew services start redis
Install with ``pip``
::
pip install mocp-cli
Optional Install yt-helper
~~~~~~~~~~~~~~~~~~~~~~~~~~
A lot of what powers the cool interactive features are provided by the
``COMMENTS`` and ``FILES`` ``redis_helper.Collections`` defined in
``yt_helper``.
Install with ``pip``
::
pip install yt-helper
or
::
pip install "mocp-cli[extras]"
QuickStart
----------
Calling ``mocplayer`` will start a REPL that will send commands to the
running instance of ``mocp --server``. Any arguments passed to
``mocplayer`` are assumed to be glob patterns that should be passed to
the ``moc.find_select_and_play`` function.
.. code:: bash
# Start the interactive player with audio files
mocplayer ~/Music/*.mp3
# Or start with a specific directory
mocplayer ~/Podcasts/
**Basic Controls:** - ``space`` - pause/unpause - ``m`` - mark current
timestamp for later reference - ``c`` - show all comments/marks for
current file - ``i`` - show info about currently playing file - ``n`` -
next file in playlist - ``p`` - previous file in playlist - ``h``/``l``
- seek backward/forward (5 seconds) - ``H``/``L`` - seek
backward/forward (30 seconds) - ``←``/``→`` - seek backward/forward (1
second, arrow keys) - ``j``/``k`` - volume down/up - ``↓``/``↑`` -
volume down/up (arrow keys) - ``f`` - find and play audio files in
current directory - ``F`` - find, select, and play audio files in
current directory - ``-`` - add timestamped comment with custom text -
``q`` - quit - ``Q`` - stop MOC server and quit
**Advanced Features:** - ``J`` - jump to a previously saved mark - ``C``
- browse and play most-commented files - ``R`` - browse and play
recently added files - ``Ctrl+a`` - start jumploop with first 62 marks
selected - ``e`` - edit timestamp of existing comment/mark - ``d`` -
delete selected comments/marks - ``D`` - delete current file and remove
all associated data
**Colon Commands:** - ``:seek N`` - seek forward/backward by N seconds -
``:go timestamp`` - jump to specific timestamp (e.g., ``:go 1h23m45s``,
``:go 2:15:30``) - ``:jump`` - jump to a saved comment or mark (same as
``J``) - ``:jumploop`` - start interactive mark navigation session -
``:most_commented [limit]`` - browse most-commented files (default limit
62) - ``:recent_files [limit]`` - browse recently added files (default
limit 62) - ``:delete_comments`` - select comments/marks to delete -
``:delete`` - delete current file and associated data -
``:edit_timestamp`` - edit timestamp of existing comment/mark -
``:find pattern1 pattern2`` - find and select files by glob patterns
**What you gain:** Transform passive audio consumption into an active,
searchable knowledge base. Mark key moments while listening, add
contextual notes, and build a personal audio archive that becomes more
valuable over time. Never lose track of important audio moments again.
API Overview
------------
Interactive Player Interface
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Core Player Class
^^^^^^^^^^^^^^^^^
- **``Player``** - Main interactive REPL for controlling MOC player
with vim-style keybindings
- Inherits from ``GetCharLoop`` for single-keystroke efficiency
- ``chfunc_dict``: Ordered dictionary mapping keys to (function,
help_text) tuples
- ``name``: Collection name for Redis storage (‘mocp’)
- ``prompt``: Display prompt (‘mocplayer>’)
- ``input_hook``: Function to handle timestamped comments via ``-``
input
- ``pre_input_hook``: Function to capture current timestamp context
- ``break_chars``: Characters that exit the loop ([‘q’, ‘Q’])
- Returns: Interactive session (call with ``Player()`` to start)
- Internal calls: ``GetCharLoop.__init__()``, moc module functions,
COMMENTS collection
Player Control Methods (Colon Commands)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Navigation and Seeking
^^^^^^^^^^^^^^^^^^^^^^
- **``seek(num)``** - Seek forward or backward by specified seconds
- ``num``: Number of seconds to seek (positive=forward,
negative=backward)
- Returns: None (updates playback position)
- Internal calls: moc.seek
- **``go(timestamp)``** - Jump to absolute position in current file
- ``timestamp``: String in formats like ‘3h4m5s’, ‘2:15:30’, ‘300s’,
‘300’
- Returns: None (seeks to position)
- Internal calls: moc.go
Comment and Mark Navigation
^^^^^^^^^^^^^^^^^^^^^^^^^^^
- **``jump()``** - Interactive jump to saved comment or mark
- Returns: None (opens selection interface for saved marks)
- Internal calls: ``jump_to_select()`` function
- **``jumploop()``** - Start interactive navigation session between
marks
- Returns: None (starts unbuffered navigation loop through selected
marks up to 62)
- Internal calls: ``jumploop()`` function
File Discovery and Management
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- **``most_commented(limit=62)``** - Browse and play most-commented
files
- ``limit``: Maximum number of files to display (default 62)
- Returns: None (opens selection interface for frequently annotated
files)
- Internal calls: ``most_commented_files_play_select()`` function
- **``recent_files(limit=62)``** - Browse and play recently added files
- ``limit``: Maximum number of files to display (default 62)
- Returns: None (opens selection interface for recently added files)
- Internal calls: ``recent_files_play_select()`` function
- **``find(*glob_patterns)``** - Find and select audio files by pattern
- ``*glob_patterns``: File/directory glob patterns to search
- Returns: None (opens selection interface for matching files)
- Internal calls: moc.find_select_and_play
Comment Management
^^^^^^^^^^^^^^^^^^
- **``delete_comments()``** - Select and delete comments/marks for
current file
- Returns: None (opens selection interface for comment deletion)
- Internal calls: ``delete_comments_select()`` function
- **``edit_timestamp()``** - Edit timestamp of existing comment/mark
- Returns: None (opens selection interface for timestamp editing)
- Internal calls: ``edit_comment_timestamp_select()`` function
File Operations
^^^^^^^^^^^^^^^
- **``delete()``** - Delete current audio file and remove all
associated data
- Returns: None (removes file from filesystem, updates FILES
collection, removes COMMENTS)
- Internal calls: ``delete()`` function
Raw data
{
"_id": null,
"home_page": "https://github.com/kenjyco/mocp-cli",
"name": "mocp-cli",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "moc, mocp, cli, command-line, console audio, repl, mp3 player, kenjyco",
"author": "Ken",
"author_email": "kenjyco@gmail.com",
"download_url": "https://github.com/kenjyco/mocp-cli/tarball/v0.1.22",
"platform": null,
"description": "A sophisticated interactive music player built on MOC (Music on Console)\nand the `chloop <https://github.com/kenjyco/chloop>`__ REPL framework\nthat transforms audio listening into an intelligent, annotated\nexperience. This library provides vim-style keyboard controls, timestamp\nmarking, and persistent comment storage to help users deeply engage with\naudio content.\n\nThe core philosophy centers on **active listening workflows** where\nusers can mark interesting moments, add contextual notes, and build\nsearchable audio archives over time. Whether analyzing podcasts,\nstudying music, reviewing recordings, or conducting audio research,\nmocp-cli reduces the mental overhead of navigating complex audio files\nby making annotation and navigation effortless.\n\nThe library integrates seamlessly with Redis-based data storage and the\nbroader helper library ecosystem, enabling powerful audio workflow\nautomation and cross-session persistence.\n\nInstall\n-------\n\nInstall the actual `MOC player/server <https://moc.daper.net/>`__\n\n::\n\n sudo apt-get install -y moc\n\nor\n\n::\n\n brew install moc\n\nIf you **don\u2019t\nhave**\\ `docker <https://docs.docker.com/get-docker>`__\\ **installed**,\ninstall Redis and start server\n\n::\n\n sudo apt-get install -y redis-server\n\nor\n\n::\n\n brew install redis\n brew services start redis\n\nInstall with ``pip``\n\n::\n\n pip install mocp-cli\n\nOptional Install yt-helper\n~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nA lot of what powers the cool interactive features are provided by the\n``COMMENTS`` and ``FILES`` ``redis_helper.Collections`` defined in\n``yt_helper``.\n\nInstall with ``pip``\n\n::\n\n pip install yt-helper\n\nor\n\n::\n\n pip install \"mocp-cli[extras]\"\n\nQuickStart\n----------\n\nCalling ``mocplayer`` will start a REPL that will send commands to the\nrunning instance of ``mocp --server``. Any arguments passed to\n``mocplayer`` are assumed to be glob patterns that should be passed to\nthe ``moc.find_select_and_play`` function.\n\n.. code:: bash\n\n # Start the interactive player with audio files\n mocplayer ~/Music/*.mp3\n\n # Or start with a specific directory\n mocplayer ~/Podcasts/\n\n**Basic Controls:** - ``space`` - pause/unpause - ``m`` - mark current\ntimestamp for later reference - ``c`` - show all comments/marks for\ncurrent file - ``i`` - show info about currently playing file - ``n`` -\nnext file in playlist - ``p`` - previous file in playlist - ``h``/``l``\n- seek backward/forward (5 seconds) - ``H``/``L`` - seek\nbackward/forward (30 seconds) - ``\u2190``/``\u2192`` - seek backward/forward (1\nsecond, arrow keys) - ``j``/``k`` - volume down/up - ``\u2193``/``\u2191`` -\nvolume down/up (arrow keys) - ``f`` - find and play audio files in\ncurrent directory - ``F`` - find, select, and play audio files in\ncurrent directory - ``-`` - add timestamped comment with custom text -\n``q`` - quit - ``Q`` - stop MOC server and quit\n\n**Advanced Features:** - ``J`` - jump to a previously saved mark - ``C``\n- browse and play most-commented files - ``R`` - browse and play\nrecently added files - ``Ctrl+a`` - start jumploop with first 62 marks\nselected - ``e`` - edit timestamp of existing comment/mark - ``d`` -\ndelete selected comments/marks - ``D`` - delete current file and remove\nall associated data\n\n**Colon Commands:** - ``:seek N`` - seek forward/backward by N seconds -\n``:go timestamp`` - jump to specific timestamp (e.g., ``:go 1h23m45s``,\n``:go 2:15:30``) - ``:jump`` - jump to a saved comment or mark (same as\n``J``) - ``:jumploop`` - start interactive mark navigation session -\n``:most_commented [limit]`` - browse most-commented files (default limit\n62) - ``:recent_files [limit]`` - browse recently added files (default\nlimit 62) - ``:delete_comments`` - select comments/marks to delete -\n``:delete`` - delete current file and associated data -\n``:edit_timestamp`` - edit timestamp of existing comment/mark -\n``:find pattern1 pattern2`` - find and select files by glob patterns\n\n**What you gain:** Transform passive audio consumption into an active,\nsearchable knowledge base. Mark key moments while listening, add\ncontextual notes, and build a personal audio archive that becomes more\nvaluable over time. Never lose track of important audio moments again.\n\nAPI Overview\n------------\n\nInteractive Player Interface\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nCore Player Class\n^^^^^^^^^^^^^^^^^\n\n- **``Player``** - Main interactive REPL for controlling MOC player\n with vim-style keybindings\n\n - Inherits from ``GetCharLoop`` for single-keystroke efficiency\n - ``chfunc_dict``: Ordered dictionary mapping keys to (function,\n help_text) tuples\n - ``name``: Collection name for Redis storage (\u2018mocp\u2019)\n - ``prompt``: Display prompt (\u2018mocplayer>\u2019)\n - ``input_hook``: Function to handle timestamped comments via ``-``\n input\n - ``pre_input_hook``: Function to capture current timestamp context\n - ``break_chars``: Characters that exit the loop ([\u2018q\u2019, \u2018Q\u2019])\n - Returns: Interactive session (call with ``Player()`` to start)\n - Internal calls: ``GetCharLoop.__init__()``, moc module functions,\n COMMENTS collection\n\nPlayer Control Methods (Colon Commands)\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nNavigation and Seeking\n^^^^^^^^^^^^^^^^^^^^^^\n\n- **``seek(num)``** - Seek forward or backward by specified seconds\n\n - ``num``: Number of seconds to seek (positive=forward,\n negative=backward)\n - Returns: None (updates playback position)\n - Internal calls: moc.seek\n\n- **``go(timestamp)``** - Jump to absolute position in current file\n\n - ``timestamp``: String in formats like \u20183h4m5s\u2019, \u20182:15:30\u2019, \u2018300s\u2019,\n \u2018300\u2019\n - Returns: None (seeks to position)\n - Internal calls: moc.go\n\nComment and Mark Navigation\n^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\n- **``jump()``** - Interactive jump to saved comment or mark\n\n - Returns: None (opens selection interface for saved marks)\n - Internal calls: ``jump_to_select()`` function\n\n- **``jumploop()``** - Start interactive navigation session between\n marks\n\n - Returns: None (starts unbuffered navigation loop through selected\n marks up to 62)\n - Internal calls: ``jumploop()`` function\n\nFile Discovery and Management\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\n- **``most_commented(limit=62)``** - Browse and play most-commented\n files\n\n - ``limit``: Maximum number of files to display (default 62)\n - Returns: None (opens selection interface for frequently annotated\n files)\n - Internal calls: ``most_commented_files_play_select()`` function\n\n- **``recent_files(limit=62)``** - Browse and play recently added files\n\n - ``limit``: Maximum number of files to display (default 62)\n - Returns: None (opens selection interface for recently added files)\n - Internal calls: ``recent_files_play_select()`` function\n\n- **``find(*glob_patterns)``** - Find and select audio files by pattern\n\n - ``*glob_patterns``: File/directory glob patterns to search\n - Returns: None (opens selection interface for matching files)\n - Internal calls: moc.find_select_and_play\n\nComment Management\n^^^^^^^^^^^^^^^^^^\n\n- **``delete_comments()``** - Select and delete comments/marks for\n current file\n\n - Returns: None (opens selection interface for comment deletion)\n - Internal calls: ``delete_comments_select()`` function\n\n- **``edit_timestamp()``** - Edit timestamp of existing comment/mark\n\n - Returns: None (opens selection interface for timestamp editing)\n - Internal calls: ``edit_comment_timestamp_select()`` function\n\nFile Operations\n^^^^^^^^^^^^^^^\n\n- **``delete()``** - Delete current audio file and remove all\n associated data\n\n - Returns: None (removes file from filesystem, updates FILES\n collection, removes COMMENTS)\n - Internal calls: ``delete()`` function\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "CLI tools for finding, organizing, and playing audio files",
"version": "0.1.22",
"project_urls": {
"Download": "https://github.com/kenjyco/mocp-cli/tarball/v0.1.22",
"Homepage": "https://github.com/kenjyco/mocp-cli"
},
"split_keywords": [
"moc",
" mocp",
" cli",
" command-line",
" console audio",
" repl",
" mp3 player",
" kenjyco"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5f5479a54371fa1b04295a4c8e05e563512db8907d8aa4384355a9ba249d5838",
"md5": "ec8b1ae4d2b72f7ff4d41bb1d7d7e9fb",
"sha256": "dc5a55675645ba0aa3a5a313058fabd796bba688da33418b220f1fbc5445435a"
},
"downloads": -1,
"filename": "mocp_cli-0.1.22-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ec8b1ae4d2b72f7ff4d41bb1d7d7e9fb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 9558,
"upload_time": "2025-07-23T18:36:16",
"upload_time_iso_8601": "2025-07-23T18:36:16.590852Z",
"url": "https://files.pythonhosted.org/packages/5f/54/79a54371fa1b04295a4c8e05e563512db8907d8aa4384355a9ba249d5838/mocp_cli-0.1.22-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-23 18:36:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kenjyco",
"github_project": "mocp-cli",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "bg-helper",
"specs": []
},
{
"name": "chloop",
"specs": []
},
{
"name": "click",
"specs": [
[
">=",
"6.0"
]
]
},
{
"name": "input-helper",
"specs": []
},
{
"name": "mocp",
"specs": []
}
],
"lcname": "mocp-cli"
}
JSON
