Skip to content

Latest commit

 

History

History
270 lines (195 loc) · 7.04 KB

PLAYBACK_CONTROLS.md

File metadata and controls

270 lines (195 loc) · 7.04 KB

MPV Playback Controls

The media server now includes full playback control for MPV using IPC (Inter-Process Communication). This allows you to control a running MPV instance remotely.

How It Works

When you play a movie with MPV, the server starts it with an IPC socket at /tmp/mpv-ipc-socket. This socket allows sending JSON-RPC commands to control playback.

Available Commands

Basic Playback

play

# Play a movie (with MPV IPC enabled)
python media_client.py --protocol stdio --command play --movie "Airplane!.mp4"

# Play with loop enabled
python media_client.py --protocol stdio --command play --movie "Airplane!.mp4" --loop

pause

# Toggle pause/unpause
python media_client.py --protocol stdio --command pause

stop

# Stop playback and quit MPV
python media_client.py --protocol stdio --command stop

Seeking

seek-forward

# Skip forward 10 seconds (default)
python media_client.py --protocol stdio --command seek-forward

# Skip forward 30 seconds
python media_client.py --protocol stdio --command seek-forward --seconds 30

seek-backward

# Skip backward 10 seconds (default)
python media_client.py --protocol stdio --command seek-backward

# Skip backward 15 seconds
python media_client.py --protocol stdio --command seek-backward --seconds 15

restart

# Restart from beginning
python media_client.py --protocol stdio --command restart

Chapter Navigation

For videos with chapters (like DVDs or structured videos):

next-chapter

# Jump to next chapter/scene
python media_client.py --protocol stdio --command next-chapter

previous-chapter

# Jump to previous chapter/scene
python media_client.py --protocol stdio --command previous-chapter

Loop Control

toggle-loop

# Toggle loop mode on/off
python media_client.py --protocol stdio --command toggle-loop

HTTP/HTTPS Control

All commands work over HTTP/HTTPS as well:

# Start server
python media_server.py --transport http --host 0.0.0.0 --port 8000

# Play a movie
python media_client.py --protocol http --url http://localhost:8000/sse \
    --command play --movie "Airplane!.mp4"

# Pause
python media_client.py --protocol http --url http://localhost:8000/sse \
    --command pause

# Seek forward
python media_client.py --protocol http --url http://localhost:8000/sse \
    --command seek-forward --seconds 30

Complete Command Reference

Command Arguments Description
list None List all available movies
play --movie <file> --loop (optional) Play a movie
pause None Toggle pause/play
stop None Stop and quit
seek-forward --seconds <n> (optional, default: 10) Skip forward
seek-backward --seconds <n> (optional, default: 10) Skip backward
next-chapter None Next chapter/scene
previous-chapter None Previous chapter/scene
toggle-loop None Toggle loop mode
restart None Restart from beginning

Example Usage Scenarios

Remote Movie Night

# On the media server (Raspberry Pi, etc.)
python media_server.py --transport http --host 0.0.0.0 --port 8000

# From your phone/laptop/another device
# List movies
python media_client.py --protocol http --url http://192.168.1.100:8000/sse --command list

# Start the movie
python media_client.py --protocol http --url http://192.168.1.100:8000/sse \
    --command play --movie "The Fantastic 4 First Steps.mp4"

# Pause for bathroom break
python media_client.py --protocol http --url http://192.168.1.100:8000/sse --command pause

# Resume
python media_client.py --protocol http --url http://192.168.1.100:8000/sse --command pause

# Skip opening credits
python media_client.py --protocol http --url http://192.168.1.100:8000/sse \
    --command seek-forward --seconds 60

# Rewind to catch a line
python media_client.py --protocol http --url http://192.168.1.100:8000/sse \
    --command seek-backward --seconds 5

# Stop when done
python media_client.py --protocol http --url http://192.168.1.100:8000/sse --command stop

Automated Playback

#!/bin/bash
# play_movie_sequence.sh - Play a sequence with control

# Start first movie
python media_client.py --protocol stdio --command play --movie "Movie1.mp4"

sleep 10

# Skip intro
python media_client.py --protocol stdio --command seek-forward --seconds 30

# Wait for it to finish (implement your own wait logic)
# ...

# Play next movie
python media_client.py --protocol stdio --command play --movie "Movie2.mp4"

Claude Desktop Integration

With Claude Desktop, you can use natural language:

User: Play Airplane
Claude: [uses play_movie tool]

User: Pause it
Claude: [uses pause_playback tool]

User: Skip forward 30 seconds
Claude: [uses seek_forward tool with seconds: 30]

User: Go back to the beginning
Claude: [uses restart_playback tool]

User: Stop playback
Claude: [uses stop_playback tool]

MPV Commands Reference

The server uses these MPV IPC commands:

Tool MPV Command Effect
pause_playback cycle pause Toggle pause state
stop_playback quit Exit MPV
seek_forward seek <n> relative Seek forward
seek_backward seek -<n> relative Seek backward
restart_playback seek 0 absolute Jump to start
next_chapter add chapter 1 Next chapter
previous_chapter add chapter -1 Previous chapter
toggle_loop cycle loop-file Toggle loop mode

Advanced: Direct Socket Communication

You can also communicate directly with the MPV socket:

# Using echo and socat
echo '{"command": ["cycle", "pause"]}' | socat - /tmp/mpv-ipc-socket

# Get current position
echo '{"command": ["get_property", "time-pos"]}' | socat - /tmp/mpv-ipc-socket

Troubleshooting

"MPV is not running or IPC socket not found"

Problem: Trying to control playback when no movie is playing.

Solution: Start playing a movie first:

python media_client.py --protocol stdio --command play --movie "YourMovie.mp4"

Controls don't work with VLC

Problem: VLC doesn't support the same IPC mechanism.

Solution: The server automatically uses MPV when available. Make sure MPV is installed:

sudo apt install mpv  # Linux
brew install mpv      # macOS

Socket permission errors

Problem: Can't connect to /tmp/mpv-ipc-socket.

Solution: The socket is created with user-only permissions. Run the client as the same user that started MPV.

Platform Support

Platform MPV IPC Support Fallback
Linux ✓ Yes VLC, MPlayer
macOS ✓ Yes open command
Windows ✓ Yes startfile

Future Enhancements

Possible additions:

  • Volume control
  • Subtitle track selection
  • Audio track selection
  • Playback speed control
  • Screenshot capture
  • Playlist management
  • Query current position/duration
  • Query playing status

To request features, modify media_server.py:line233 (@app.list_tools) and add new tool definitions.