New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve doc/protocol description #340

Open
Grundligt opened this Issue Aug 13, 2018 · 3 comments

Comments

Projects
None yet
2 participants
@Grundligt

Grundligt commented Aug 13, 2018

Working on a server using the MPD protocol but can't find anything actually mentioning nor showing a single example of a successful command -> response transaction, specifically how and when the server should format and send its response.

How do I format a simple response to a command requesting the status? Before the OK?

client: status\n server: volume 24\n repeat 0\n OK\n

The mpc failed to parse the response. After? The same thing.

Do I format the response like this maybe?

status volume 24\n status repeat 0\n OK\n

When and how do I respond to a command_ok_list? Before or directly after a list_OK? After the last list_OK?

It's nice with an ACK example on the page named response_syntax, but at least the basic examples or for that matter, any mention of how the server should respond to a command requiring information wouldn't hurt.

And I really like

The return value is whatever the return for a list of commands is.

https://www.musicpd.org/doc/protocol/command_lists.html

@MaxKellermann

This comment has been minimized.

Show comment
Hide comment
@MaxKellermann

MaxKellermann Aug 14, 2018

Member

Multi-line responses should be multi-line in the documentation as well - i.e. no \n escape codes.
I don't understand your comand list question.
You're right that this documentation page is pretty badly phrased - it's still the original text from >10 years ago before I entered MPD development - blame my predecessos for writing such a text, and blame me for not rewriting it in 10 years ;)

Member

MaxKellermann commented Aug 14, 2018

Multi-line responses should be multi-line in the documentation as well - i.e. no \n escape codes.
I don't understand your comand list question.
You're right that this documentation page is pretty badly phrased - it's still the original text from >10 years ago before I entered MPD development - blame my predecessos for writing such a text, and blame me for not rewriting it in 10 years ;)

@Grundligt

This comment has been minimized.

Show comment
Hide comment
@Grundligt

Grundligt Aug 14, 2018

Alright,

Lets say MPC for example sends,

command_list_ok_begin\n
status\n
currentsong\n
command_ok_list_end\n

Should the server response look like this?

volume 25 repeat 0 random 1 single 0...\n
list_OK\n
song info...\n
list_OK\n
OK\n

I'd be happy to help rewrite it when I understand the basics :)

EDIT:

Alright, was just the simple matter of a colon infront of each response object.

volume: 0-100 or -1 if the volume cannot be determined

https://www.musicpd.org/doc/protocol/command_reference.html

This line aren't really clear whether it just describes the volume value or actually shows the response format and value with that colon ^^

Will get to rewrite the protocol docs later on this month if you want.

Grundligt commented Aug 14, 2018

Alright,

Lets say MPC for example sends,

command_list_ok_begin\n
status\n
currentsong\n
command_ok_list_end\n

Should the server response look like this?

volume 25 repeat 0 random 1 single 0...\n
list_OK\n
song info...\n
list_OK\n
OK\n

I'd be happy to help rewrite it when I understand the basics :)

EDIT:

Alright, was just the simple matter of a colon infront of each response object.

volume: 0-100 or -1 if the volume cannot be determined

https://www.musicpd.org/doc/protocol/command_reference.html

This line aren't really clear whether it just describes the volume value or actually shows the response format and value with that colon ^^

Will get to rewrite the protocol docs later on this month if you want.

@MaxKellermann

This comment has been minimized.

Show comment
Hide comment
@MaxKellermann

MaxKellermann Aug 14, 2018

Member

The "status" response is multi-line; each line describes one attribute as described in the documentation; format is NAME: VALUE. If you want to know how it looks like, try telnet/netcat to any MPD and type the command.
As bad as it is, the MPD protocol documentation has survived for 15 years because looking at real MPD responses answers most questions.
btw. the protocol documentation is still in DocBook format; the user and developer manual have already been converted to Sphinx (an implementation of reStructuredText). Editing DocBook is somewhat cumbersome.

Member

MaxKellermann commented Aug 14, 2018

The "status" response is multi-line; each line describes one attribute as described in the documentation; format is NAME: VALUE. If you want to know how it looks like, try telnet/netcat to any MPD and type the command.
As bad as it is, the MPD protocol documentation has survived for 15 years because looking at real MPD responses answers most questions.
btw. the protocol documentation is still in DocBook format; the user and developer manual have already been converted to Sphinx (an implementation of reStructuredText). Editing DocBook is somewhat cumbersome.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment