Add a client API example

DOCS/client_api_examples/shared.h

@@ -0,0 +1,10 @@
+#include <stdio.h>
+#include <stdlib.h>
+
+static inline void check_error(int status)
+{
+    if (status < 0) {
+        printf("mpv API error: %s\n", mpv_error_string(status));
+        exit(1);
+    }
+}

DOCS/client_api_examples/simple.c

@@ -0,0 +1,43 @@
+#include <stddef.h>
+#include <stdio.h>
+#include <stdlib.h>
+
+#include "libmpv/client.h"
+#include "shared.h"
+
+int main(int argc, char *argv[])
+{
+    if (argc != 2) {
+        printf("pass a single media file as argument\n");
+        return 1;
+    }
+
+    mpv_handle *ctx = mpv_create();
+    if (!ctx) {
+        printf("failed creating context\n");
+        return 1;
+    }
+
+    // Enable default key bindings, so the user can actually interact with
+    // the player (and e.g. close the window).
+    check_error(mpv_set_option_string(ctx, "input-default-bindings", "yes"));
+    check_error(mpv_set_option_string(ctx, "osc", "yes"));
+
+    // Done setting up options.
+    check_error(mpv_initialize(ctx));
+
+    // Play this file.
+    const char *cmd[] = {"loadfile", argv[1], NULL};
+    check_error(mpv_command(ctx, cmd));
+
+    // Let it play, and wait until the user quits.
+    while (1) {
+        mpv_event *event = mpv_wait_event(ctx, 10000);
+        printf("event: %s\n", mpv_event_name(event->event_id));
+        if (event->event_id == MPV_EVENT_SHUTDOWN)
+            break;
+    }
+
+    mpv_destroy(ctx);
+    return 0;
+}

wscript

@@ -14,6 +14,11 @@ build_options = [
         'desc': 'enable shared library',
         'default': 'disable',
         'func': check_true
+    }, {
+        'name': '--client-api-examples',
+        'desc': 'build client API examples',
+        'deps': ['shared'],
+        'func': check_true
     }, {
         'name': '--static-build',
         'desc': 'static build',

wscript_build.py

@@ -452,6 +452,17 @@ def build(ctx):
         for f in headers:
             ctx.install_as(ctx.env.INCDIR + '/libmpv/' + f, 'libmpv/' + f)
 
+    if ctx.dependency_satisfied('client-api-examples'):
+        # This assumes all examples are single-file (as examples should be)
+        for f in ["simple"]:
+            ctx(
+                target       = f,
+                source       = "DOCS/client_api_examples/" + f + ".c",
+                includes     = [ctx.bldnode.abspath(), ctx.srcnode.abspath()],
+                use          = "mpv",
+                features     = "c cprogram",
+            )
+
     if ctx.env.DEST_OS == 'win32':
         wrapctx = ctx(
             target       = "mpv",