Add documentationHEADmain

3 files changed, 128 insertions, 0 deletions

diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..c68262f
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,24 @@
+PREFIX ?= /usr/local
+BINDIR = $(PREFIX)/bin
+MANDIR = $(PREFIX)/share/man/man1
+
+SCRIPT = wake-pulse
+MANPAGE = wake-pulse.1
+
+.PHONY: install uninstall clean
+
+install:
+	install -d $(DESTDIR)$(BINDIR)
+	install -m 755 $(SCRIPT) $(DESTDIR)$(BINDIR)/$(SCRIPT)
+	install -d $(DESTDIR)$(MANDIR)
+	install -m 644 $(MANPAGE) $(DESTDIR)$(MANDIR)/$(MANPAGE)
+	@echo "Installed $(SCRIPT) to $(BINDIR)"
+	@echo "Installed $(MANPAGE) to $(MANDIR)"
+
+uninstall:
+	rm -f $(DESTDIR)$(BINDIR)/$(SCRIPT)
+	rm -f $(DESTDIR)$(MANDIR)/$(MANPAGE)
+	@echo "Uninstalled $(SCRIPT) and $(MANPAGE)"
+
+clean:
+	@echo "Nothing to clean"
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..72a1129
--- /dev/null
+++ b/README.md
@@ -0,0 +1,39 @@
+# wake-pulse
+
+Wake PulseAudio/PipeWire sinks from auto-suspend.
+
+## Installation
+
+```bash
+make install
+```
+
+## Usage
+
+```bash
+wake-pulse                    # Wake default sink, exit when awake
+wake-pulse -c                 # Keep default sink awake continuously
+wake-pulse -s sink_name       # Wake specific sink
+wake-pulse -s sink_name -c    # Keep specific sink awake continuously
+```
+
+## Options
+
+- `-s, --sink NAME` - Sink name to keep awake (default: system default sink)
+- `-c, --continuous` - Keep sink awake continuously (default: exit once awake)
+- `-h, --help` - Show help message
+
+## Dependencies
+
+- `bash`
+- `pulseaudio-utils` (pactl, paplay)
+
+## How It Works
+
+The script generates a silent WAV file and plays it on loop to prevent the audio sink from suspending. It monitors sink state changes via `pactl subscribe` and exits (or continues) based on the mode selected.
+
+## Uninstall
+
+```bash
+make uninstall
+```
diff --git a/wake-pulse.1 b/wake-pulse.1
new file mode 100644
index 0000000..ec7d1aa
--- /dev/null
+++ b/wake-pulse.1
@@ -0,0 +1,65 @@
+.TH WAKE-PULSE 1 "February 2026" "wake-pulse" "User Commands"
+.SH NAME
+wake-pulse \- prevent PulseAudio/PipeWire sinks from auto-suspending
+.SH SYNOPSIS
+.B wake-pulse
+[\fIOPTIONS\fR]
+.SH DESCRIPTION
+.B wake-pulse
+prevents a PulseAudio or PipeWire sink from automatically suspending by playing a silent WAV file to it. By default, it exits once the sink is no longer suspended. Use \fB-c\fR to keep it awake continuously.
+.PP
+The script generates a 1-second silent WAV file and plays it on loop to the specified sink (or the default sink if none is specified). It monitors sink state changes via \fBpactl subscribe\fR.
+.SH OPTIONS
+.TP
+.BR \-s ", " \-\-sink " " \fINAME\fR
+Specify the sink name to keep awake. If not specified, the system default sink is used.
+.TP
+.BR \-c ", " \-\-continuous
+Keep the sink awake continuously. Without this option, the script exits once the sink is no longer suspended.
+.TP
+.BR \-h ", " \-\-help
+Show help message and exit.
+.SH EXAMPLES
+.TP
+.B wake-pulse
+Wake the default sink and exit once it is awake.
+.TP
+.B wake-pulse -c
+Keep the default sink awake continuously until interrupted.
+.TP
+.B wake-pulse -s my_sink_name
+Wake a specific sink named \fImy_sink_name\fR.
+.TP
+.B wake-pulse -s my_sink -c
+Keep a specific sink awake continuously.
+.SH FILES
+.TP
+.I /tmp/wake-pulse-silence.wav
+Temporary silent WAV file used for playback.
+.TP
+.I /tmp/wake-pulse-$$.pid
+PID file for the playback process.
+.TP
+.I /tmp/wake-pulse-silence.lock
+Lock file for atomic silence file creation.
+.SH DEPENDENCIES
+.TP
+.B pactl
+PulseAudio control utility (from pulseaudio-utils package).
+.TP
+.B paplay
+PulseAudio playback utility (from pulseaudio-utils package).
+.SH EXIT STATUS
+.TP
+.B 0
+Success (sink was woken or kept awake).
+.TP
+.B 1
+Error (invalid options, sink not found, or other failure).
+.SH AUTHOR
+Written for PulseAudio and PipeWire users who need to prevent automatic sink suspension.
+.SH SEE ALSO
+.BR pactl (1),
+.BR paplay (1),
+.BR pulseaudio (1),
+.BR pipewire (1)