summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorwm4 <wm4@nowhere>2015-02-14 14:36:48 +0100
committerDiogo Franco (Kovensky) <diogomfranco@gmail.com>2015-02-16 18:14:10 +0900
commitb476d21d0a6c97b59d5da4d00cc4f5b3a8b57be6 (patch)
tree57f8a143890d792fb08350206ce0b03dc5f20177
parent16c7de4aab72eb0898eefa38771ad0a2365f9256 (diff)
downloadmpv-b476d21d0a6c97b59d5da4d00cc4f5b3a8b57be6.tar.bz2
mpv-b476d21d0a6c97b59d5da4d00cc4f5b3a8b57be6.tar.xz
client API: clarify filename string encoding
Admittedly, the behavior on Windows is not quite straightforward. The behavior on the other platforms is equivalent to fopen(). Fixes #1585. (cherry picked from commit a799a4c57f998ed2ef7f5d306d4dad32c173c349)
-rw-r--r--libmpv/client.h24
1 files changed, 24 insertions, 0 deletions
diff --git a/libmpv/client.h b/libmpv/client.h
index 500f03cd94..0ccb2068e1 100644
--- a/libmpv/client.h
+++ b/libmpv/client.h
@@ -121,6 +121,27 @@ extern "C" {
* process (such as ffmpeg OpenSSL support, or the mpv IPC code).
* - On memory exhaustion, mpv will kill the process.
*
+ * Encoding of filenames
+ * ---------------------
+ *
+ * mpv uses UTF-8 everywhere.
+ *
+ * On some platforms (like Linux), filenames actually do not have to be UTF-8;
+ * for this reason libmpv supports non-UTF-8 strings. libmpv uses what the
+ * kernel uses and does not recode filenames. At least on Linux, passing a
+ * string to libmpv is like passing a string to the fopen() function.
+ *
+ * On Windows, filenames are always UTF-8, libmpv converts between UTF-8 and
+ * UTF-16 when using win32 API functions. libmpv never uses or accepts
+ * filenames in the local 8 bit encoding. It does not use fopen() either;
+ * it uses _wfopen().
+ *
+ * On OS X, filenames and other strings taken/returned by libmpv can have
+ * inconsistent unicode normalization. This can sometimes lead to problems.
+ * You have to hope for the best.
+ *
+ * Also see the remarks for MPV_FORMAT_STRING.
+ *
* Embedding the video window
* --------------------------
*
@@ -502,6 +523,9 @@ typedef enum mpv_format {
* and even filenames don't necessarily have to be in UTF-8 (at
* least on Linux). If you pass the strings to code that requires
* valid UTF-8, you have to sanitize it in some way.
+ * On Windows, filenames are always UTF-8, and libmpv converts
+ * between UTF-8 and UTF-16 when using win32 API functions. See
+ * the "Encoding of filenames" section for details.
*
* Example for reading:
*