1 files changed, 89 insertions, 0 deletions
diff --git a/doc/api.dox b/doc/api.dox
new file mode 100644
index 0000000..880127e
--- /dev/null
+++ b/doc/api.dox
@@ -0,0 +1,89 @@
+/** \page page_api PipeWire API
+
+The PipeWire API consists of several parts:
+
+- The \ref pw_stream for a convenient way to send and receive data streams from/to PipeWire.
+
+- The \ref pw_filter for a convenient way to implement processing filters.
+
+- The \ref api_pw_core to access a PipeWire instance. This API is used
+by all clients that need to communicate with the \ref page_daemon and provides
+the necessary structs to interface with the daemon.
+
+- The \ref api_pw_impl is primarily used by the \ref page_daemon itself but also by the
+\ref page_session_manager and modules/extensions that need to build objects in
+the graph.
+
+- The \ref api_pw_util containing various utility functions and structures.
+
+- The \ref api_pw_ext for interfacing with certain extension modules.
+
+The APIs work through proxy objects, so that calling a method on an object
+invokes that same method on the remote side. Marshalling and de-marshalling is
+handled transparently by the \ref page_module_protocol_native.
+The below graph illustrates this approach:
+
+\dot
+digraph API {
+  compound=true;
+  node [shape="box"];
+  rankdir="RL";
+
+  subgraph cluster_daemon {
+       rankdir="TB";
+       label="PipeWire daemon";
+       style="dashed";
+
+       impl_core [label="Core Impl. Object"];
+       impl_device [label="Device Impl. Object"];
+       impl_node [label="Node Impl. Object"];
+  }
+
+  subgraph cluster_client {
+       rankdir="TB";
+       label="PipeWire client";
+       style="dashed";
+
+       obj_core [label="Core Object"];
+       obj_device [label="Device Object"];
+       obj_node [label="Node Object"];
+  }
+
+  obj_core -> impl_core;
+  obj_device -> impl_device;
+  obj_node -> impl_node;
+
+}
+\enddot
+
+It is common for clients to use both the \ref api_pw_core and the \ref api_pw_impl
+and both APIs are provided by the same library.
+
+- \subpage page_client_impl
+- \subpage page_proxy
+- \subpage page_streams
+- \subpage page_thread_loop
+
+
+\addtogroup api_pw_core Core API
+
+The Core API to access a PipeWire instance. This API is used by all
+clients to communicate with the \ref page_daemon.
+
+If you are familiar with Wayland implementation, the Core API is
+roughly equivalent to libwayland-client.
+
+See: \ref page_api
+
+
+\addtogroup api_pw_impl Implementation API
+
+The implementation API provides the tools to build new objects and
+modules.
+
+If you are familiar with Wayland implementation, the Implementation API is
+roughly equivalent to libwayland-server.
+
+See: \ref page_api
+
+*/