diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in
index 6c7118d0d..82ec2edb6 100644
--- a/doc/Doxyfile.in
+++ b/doc/Doxyfile.in
@@ -22,9 +22,9 @@ INPUT = @inputs@
FILTER_PATTERNS = "*.c=@c_input_filter@" "*.h=@h_input_filter@"
FILE_PATTERNS = "*.h" "*.c"
RECURSIVE = YES
-EXAMPLE_PATH = "@top_srcdir@/src/tools" \
- "@top_srcdir@/src/examples"
-
+EXAMPLE_PATH = "@top_srcdir@/src/examples" \
+ "@top_srcdir@/spa/examples"
+EXAMPLE_PATTERNS = "*.c"
REFERENCED_BY_RELATION = NO
REFERENCES_RELATION = NO
diff --git a/doc/examples.dox.in b/doc/examples.dox.in
new file mode 100644
index 000000000..fd11ac890
--- /dev/null
+++ b/doc/examples.dox.in
@@ -0,0 +1,9 @@
+/**
+
+\page page_examples List of example programs
+
+@example_ref@
+
+@example_doxygen@
+
+*/
diff --git a/doc/meson.build b/doc/meson.build
index 9857e7dec..b4ae72f76 100644
--- a/doc/meson.build
+++ b/doc/meson.build
@@ -84,6 +84,49 @@ cssfiles = [
meson.source_root() / 'doc' / 'custom.css'
]
+# Example files (in order from simple to esoteric)
+example_files = [
+ 'audio-src.c',
+ 'audio-dsp-src.c',
+ 'audio-dsp-filter.c',
+ 'video-play.c',
+ 'video-src.c',
+ 'video-dsp-play.c',
+ 'video-play-pull.c',
+ 'video-play-reneg.c',
+ 'video-src-alloc.c',
+ 'video-src-reneg.c',
+ 'export-sink.c',
+ 'export-source.c',
+ 'export-spa.c',
+ 'export-spa-device.c',
+ 'bluez-session.c',
+ 'local-v4l2.c',
+ 'spa/examples/adapter-control.c',
+ 'spa/examples/example-control.c',
+ 'spa/examples/local-libcamera.c',
+ 'spa/examples/local-v4l2.c',
+]
+
+example_doxygen = []
+example_ref = []
+foreach h : example_files
+ example_doxygen += ['\\example ' + h,
+ '\\snippet{doc} ' + h + ' title',
+ '
',
+ '\\snippet{doc} ' + h + ' doc']
+ example_ref += ['- \\ref ' + h + ' "": \snippet{doc} ' + h + ' title']
+endforeach
+
+examples_dox_conf = configuration_data()
+examples_dox_conf.set('example_doxygen', '\n'.join(example_doxygen))
+examples_dox_conf.set('example_ref', '\n'.join(example_ref))
+examples_dox = configure_file(input: 'examples.dox.in',
+ output: 'examples.dox',
+ configuration: examples_dox_conf)
+
+input_dirs += [ 'doc/examples.dox' ]
+
doxyfile_conf.set('inputs', ' '.join(inputs + input_dirs))
doxyfile_conf.set('cssfiles', ' '.join(cssfiles))
doxyfile_conf.set('path_prefixes', ' '.join(path_prefixes))
@@ -100,7 +143,7 @@ if docdir == ''
endif
html_target = custom_target('pipewire-docs',
- input: [ doxyfile ] + inputs + cssfiles,
+ input: [ doxyfile, examples_dox ] + inputs + cssfiles,
output: [ 'html' ],
command: [ doxygen, doxyfile ],
install: true,
diff --git a/doc/tutorial.dox b/doc/tutorial.dox
index 275cb5194..e9c70fc6f 100644
--- a/doc/tutorial.dox
+++ b/doc/tutorial.dox
@@ -10,4 +10,11 @@ PipeWire API step-by-step with simple short examples.
- \subpage page_tutorial5
- \subpage page_tutorial6
+## More example programs
+
+- \ref audio-src.c "": \snippet{doc} audio-src.c title
+- \ref audio-dsp-filter.c "": \snippet{doc} audio-dsp-filter.c title
+- \ref video-play.c "": \snippet{doc} video-play.c title
+- \subpage page_examples
+
*/
diff --git a/spa/examples/adapter-control.c b/spa/examples/adapter-control.c
index af6f41f86..39a22a4e2 100644
--- a/spa/examples/adapter-control.c
+++ b/spa/examples/adapter-control.c
@@ -22,6 +22,16 @@
* DEALINGS IN THE SOFTWARE.
*/
+/*
+ [title]
+ Running audioadapter nodes.
+ [title]
+ [doc]
+ Runs an output audioadapter using audiotestsrc as follower
+ with an input audioadapter using alsa-pcm-sink as follower
+ for easy testing.
+ [doc]
+ */
#include "config.h"
diff --git a/spa/examples/example-control.c b/spa/examples/example-control.c
index 3eedc8710..f26960cd8 100644
--- a/spa/examples/example-control.c
+++ b/spa/examples/example-control.c
@@ -22,6 +22,11 @@
* DEALINGS IN THE SOFTWARE.
*/
+/*
+ [title]
+ [title]
+ */
+
#include "config.h"
#include
diff --git a/spa/examples/local-libcamera.c b/spa/examples/local-libcamera.c
index 17fed5981..88ad02bfc 100644
--- a/spa/examples/local-libcamera.c
+++ b/spa/examples/local-libcamera.c
@@ -25,6 +25,12 @@
* DEALINGS IN THE SOFTWARE.
*/
+/*
+ [title]
+ Example using libspa-libcamera, with only \ref api_spa
+ [title]
+ */
+
#include "config.h"
#include
diff --git a/spa/examples/local-v4l2.c b/spa/examples/local-v4l2.c
index 6968d3af7..bd6de7b6d 100644
--- a/spa/examples/local-v4l2.c
+++ b/spa/examples/local-v4l2.c
@@ -22,6 +22,12 @@
* DEALINGS IN THE SOFTWARE.
*/
+/*
+ [title]
+ Example using libspa-v4l2, with only \ref api_spa
+ [title]
+ */
+
#include "config.h"
#include
diff --git a/src/examples/audio-dsp-filter.c b/src/examples/audio-dsp-filter.c
index e6eee1349..9f1992b48 100644
--- a/src/examples/audio-dsp-filter.c
+++ b/src/examples/audio-dsp-filter.c
@@ -22,6 +22,12 @@
* DEALINGS IN THE SOFTWARE.
*/
+/*
+ [title]
+ Audio filter using \ref pw_filter "pw_filter".
+ [title]
+ */
+
#include
#include
#include
diff --git a/src/examples/audio-dsp-src.c b/src/examples/audio-dsp-src.c
index cbef3c778..beaecfe72 100644
--- a/src/examples/audio-dsp-src.c
+++ b/src/examples/audio-dsp-src.c
@@ -22,6 +22,12 @@
* DEALINGS IN THE SOFTWARE.
*/
+/*
+ [title]
+ Audio source using \ref pw_filter "pw_filter"
+ [title]
+ */
+
#include
#include
#include
diff --git a/src/examples/audio-src.c b/src/examples/audio-src.c
index f112307ec..561672d71 100644
--- a/src/examples/audio-src.c
+++ b/src/examples/audio-src.c
@@ -22,6 +22,12 @@
* DEALINGS IN THE SOFTWARE.
*/
+/*
+ [title]
+ Audio source using \ref pw_stream "pw_stream".
+ [title]
+ */
+
#include
#include
#include
diff --git a/src/examples/bluez-session.c b/src/examples/bluez-session.c
index 08d2b9e1d..d46b5d9a0 100644
--- a/src/examples/bluez-session.c
+++ b/src/examples/bluez-session.c
@@ -22,6 +22,12 @@
* DEALINGS IN THE SOFTWARE.
*/
+/*
+ [title]
+ Using the \ref spa_device "SPA Device API", among other things.
+ [title]
+ */
+
#include
#include
#include
diff --git a/src/examples/export-sink.c b/src/examples/export-sink.c
index e9b6c8474..43234b649 100644
--- a/src/examples/export-sink.c
+++ b/src/examples/export-sink.c
@@ -22,6 +22,12 @@
* DEALINGS IN THE SOFTWARE.
*/
+/*
+ [title]
+ Exporting and implementing a video sink SPA node, using \ref api_pw_core.
+ [title]
+ */
+
#include
#include
#include
diff --git a/src/examples/export-source.c b/src/examples/export-source.c
index 8a85b9410..974c6dea5 100644
--- a/src/examples/export-source.c
+++ b/src/examples/export-source.c
@@ -22,6 +22,12 @@
* DEALINGS IN THE SOFTWARE.
*/
+/*
+ [title]
+ Exporting and implementing a video source SPA node, using \ref api_pw_core.
+ [title]
+ */
+
#include
#include
#include
diff --git a/src/examples/export-spa-device.c b/src/examples/export-spa-device.c
index 30409ecca..4629a0275 100644
--- a/src/examples/export-spa-device.c
+++ b/src/examples/export-spa-device.c
@@ -22,6 +22,12 @@
* DEALINGS IN THE SOFTWARE.
*/
+/*
+ [title]
+ Exporting and loading a SPA device, using \ref api_pw_core.
+ [title]
+ */
+
#include
#include
#include
diff --git a/src/examples/export-spa.c b/src/examples/export-spa.c
index 39f2b571a..ba2f29990 100644
--- a/src/examples/export-spa.c
+++ b/src/examples/export-spa.c
@@ -22,6 +22,12 @@
* DEALINGS IN THE SOFTWARE.
*/
+/*
+ [title]
+ Exporting and loading a SPA node, using \ref api_pw_core.
+ [title]
+ */
+
#include
#include
#include
diff --git a/src/examples/local-v4l2.c b/src/examples/local-v4l2.c
index cd9c08844..035491d85 100644
--- a/src/examples/local-v4l2.c
+++ b/src/examples/local-v4l2.c
@@ -22,6 +22,12 @@
* DEALINGS IN THE SOFTWARE.
*/
+/*
+ [title]
+ Using libspa-v4l2
+ [title]
+ */
+
#include
#include
diff --git a/src/examples/sdl.h b/src/examples/sdl.h
index b3db3073a..cb7b87a6f 100644
--- a/src/examples/sdl.h
+++ b/src/examples/sdl.h
@@ -22,6 +22,12 @@
* DEALINGS IN THE SOFTWARE.
*/
+/*
+ [title]
+ SDL2 video format conversions
+ [title]
+ */
+
#include
#include
diff --git a/src/examples/video-dsp-play.c b/src/examples/video-dsp-play.c
index 566b10243..05828b591 100644
--- a/src/examples/video-dsp-play.c
+++ b/src/examples/video-dsp-play.c
@@ -22,6 +22,12 @@
* DEALINGS IN THE SOFTWARE.
*/
+/*
+ [title]
+ Video input stream using \ref pw_filter "pw_filter".
+ [title]
+ */
+
#include
#include
#include
diff --git a/src/examples/video-play-pull.c b/src/examples/video-play-pull.c
index b831b15e8..27694fdf3 100644
--- a/src/examples/video-play-pull.c
+++ b/src/examples/video-play-pull.c
@@ -22,6 +22,12 @@
* DEALINGS IN THE SOFTWARE.
*/
+/*
+ [title]
+ Video input stream using \ref pw_stream_trigger_process, for pull mode.
+ [title]
+ */
+
#include
#include
#include
diff --git a/src/examples/video-play-reneg.c b/src/examples/video-play-reneg.c
index ee204775a..4b4d6bb39 100644
--- a/src/examples/video-play-reneg.c
+++ b/src/examples/video-play-reneg.c
@@ -22,6 +22,12 @@
* DEALINGS IN THE SOFTWARE.
*/
+/*
+ [title]
+ Video input stream using \ref pw_stream "pw_stream", with format renegotiation.
+ [title]
+ */
+
#include
#include
#include
diff --git a/src/examples/video-play.c b/src/examples/video-play.c
index 660f44dc1..e19caf717 100644
--- a/src/examples/video-play.c
+++ b/src/examples/video-play.c
@@ -22,6 +22,12 @@
* DEALINGS IN THE SOFTWARE.
*/
+/*
+ [title]
+ Video input stream using \ref pw_stream "pw_stream".
+ [title]
+ */
+
#include
#include
#include
diff --git a/src/examples/video-src-alloc.c b/src/examples/video-src-alloc.c
index 166828e1e..92d6473dc 100644
--- a/src/examples/video-src-alloc.c
+++ b/src/examples/video-src-alloc.c
@@ -22,6 +22,12 @@
* DEALINGS IN THE SOFTWARE.
*/
+/*
+ [title]
+ Allocating buffer memory and sending fds to the server.
+ [title]
+ */
+
#include "config.h"
#include
diff --git a/src/examples/video-src-reneg.c b/src/examples/video-src-reneg.c
index eda664de2..11b4c1420 100644
--- a/src/examples/video-src-reneg.c
+++ b/src/examples/video-src-reneg.c
@@ -22,6 +22,12 @@
* DEALINGS IN THE SOFTWARE.
*/
+/*
+ [title]
+ Renegotiating video producer and consumer formats with \ref pw_stream
+ [title]
+ */
+
#include "config.h"
#include
diff --git a/src/examples/video-src.c b/src/examples/video-src.c
index 403dc66f5..7457ade84 100644
--- a/src/examples/video-src.c
+++ b/src/examples/video-src.c
@@ -22,6 +22,12 @@
* DEALINGS IN THE SOFTWARE.
*/
+/*
+ [title]
+ Video source using \ref pw_stream.
+ [title]
+ */
+
#include
#include
#include