DOCS/man/input: note that properties can be unavailable on init #15230
Conversation
guidocella
force-pushed
the
property-docs
branch
from
475c2ec
to
377f9e6
Compare
That's not correct. It's documented here: https://mpv.io/manual/master/#details-on-the-script-initialization-and-lifecycle
So there is no need for the first commit, which says the same thing but in a less general way and inaccurate ("retrieve in an event like |
Because it is a bit shorter than calling utils.join_path(working_directory, path), it gives you a canonical path, and it doesn't concate working-directory before URLs.
guidocella
force-pushed
the
property-docs
branch
from
377f9e6
to
c1eda72
Compare
DOCS/man/input.rst
Outdated
| If an option is referenced, the property will normally take/return exactly the | ||
| same values as the option. In these cases, properties are merely a way to change | ||
| an option at runtime. | ||
|
|
||
| Note that some properties are unavailable until playback starts. See `Details on |
There was a problem hiding this comment.
Note that some properties are unavailable until playback starts.
I'm not sure I like this wording. It's oddly specific. Some properties won't be available until "something" happens. Example would be that video-params won't be available after audio file playback starts. Playback start doesn't guarantee that all properties are available.
Scripts are not suppose to pull the data and especially not at init time. But init time is not special, because we might go to idle state after playback, and many properties won't be available.
We need to educate users that they should observe properties or expect that any and all of them may or may not be present depending on the current player state.
I think it is the core of scripting in mpv and such vague one-liner won't help really.
There was a problem hiding this comment.
Did you see the rest of the commit? I mentioned observe_property in details on script initialization.
There was a problem hiding this comment.
You can write it in general terms without mentioning any specific circumstances like "playback starts" or file-loaded event.
This is mentioned again below in Property list and it makes more sense near the list of properties.
guidocella
force-pushed
the
property-docs
branch
from
c1eda72
to
02203b3
Compare
DOCS/man/lua.rst
Outdated
| @@ -86,7 +86,8 @@ own event handlers which you have registered with ``mp.register_event``, or | |||
| timers added with ``mp.add_timeout`` or similar. Note that since the | |||
| script starts execution concurrently with player initialization, some properties | |||
| may not be populated with meaningful values until the relevant subsystems have | |||
| initialized. | |||
| initialized. Rather than retrieving these properties are the top of scripts, you | |||
It comes up often in IRC and issues that users don't understand why the path property is initially unavailable, so link the section that mentions it from the Properties section, and expand on how to get these properties.
guidocella
force-pushed
the
property-docs
branch
from
02203b3
to
558c101
Compare
It comes up often in IRC and issues that users don't understand why the path property is initially unavailable, so document it.