Add documentation

Author: UniquePython

Makefile

@@ -1,65 +1,24 @@
-# Compiler and flags
-CC := gcc
-CFLAGS := -Wall -Wextra -Iinclude
-DEBUGFLAGS := -g
-RELEASEFLAGS := -O2
+CC      := gcc
+CFLAGS  := -Wall -Wextra -std=c99
+LIBS    := -lm
 
-# Directories
-SRC_DIR := src
-INCLUDE_DIR := include
-BUILD_DIR := build
 BIN_DIR := bin
+TARGET  := $(BIN_DIR)/test
 
-# Executable name
-TARGET := saf
+.PHONY: all test clean
 
-# Automatically detect source and object files
-SRCS := $(wildcard $(SRC_DIR)/*.c)
-OBJS := $(patsubst $(SRC_DIR)/%.c,$(BUILD_DIR)/%.o,$(SRCS))
+all: test
 
-# Default target: release build
-.PHONY: all
-all: release
+test: dirs $(TARGET)
+	./$(TARGET)
 
-# -----------------------------
-# Release build
-# -----------------------------
-.PHONY: release
-release: CFLAGS += $(RELEASEFLAGS)
-release: dirs $(BIN_DIR)/$(TARGET)
+$(TARGET): test.c saf.h
+	$(CC) $(CFLAGS) test.c -o $@ $(LIBS)
 
-# -----------------------------
-# Debug build
-# -----------------------------
-.PHONY: debug
-debug: CFLAGS += $(DEBUGFLAGS)
-debug: dirs $(BIN_DIR)/$(TARGET)
-
-# -----------------------------
-# Build executable
-# -----------------------------
-$(BIN_DIR)/$(TARGET): $(OBJS)
-	$(CC) $(OBJS) -o $@
-
-# -----------------------------
-# Build object files with dependency tracking
-# -----------------------------
-$(BUILD_DIR)/%.o: $(SRC_DIR)/%.c
-	$(CC) $(CFLAGS) -MMD -MP -c $< -o $@
-
-# Include dependency files
--include $(OBJS:.o=.d)
-
-# -----------------------------
-# Create necessary directories
-# -----------------------------
 .PHONY: dirs
 dirs:
-	@mkdir -p $(BUILD_DIR) $(BIN_DIR)
+	@mkdir -p $(BIN_DIR)
 
-# -----------------------------
-# Clean build artifacts
-# -----------------------------
 .PHONY: clean
 clean:
-	$(RM) -r $(BUILD_DIR)/* $(BIN_DIR)/*
+	$(RM) -r $(BIN_DIR)

README.md

@@ -1 +1,118 @@
-# saf
+# SAF — Simple Audio Format
+
+A minimal, portable, header-only C library for a dead-simple audio format. No magic numbers, no validation overhead, no dependencies. You own the data, you own the responsibility.
+
+## Philosophy
+
+Most audio formats carry significant overhead — chunk negotiation, codec detection, metadata sprawl. SAF doesn't. The format assumes the user knows what they're doing. If you give it a file, it trusts you. This makes it fast, simple, and easy to embed anywhere.
+
+## Format Specification
+
+| Offset | Size | Type   | Description                 |
+| ------ | ---- | ------ | --------------------------- |
+| 0      | 4    | uint32 | Sample rate (little-endian) |
+| 4      | 1    | uint8  | Channel count               |
+| 5      | 1    | uint8  | Bit depth                   |
+| 6      | ...  | raw    | PCM samples (interleaved)   |
+
+**Total header size: 6 bytes.**
+
+Samples are raw interleaved PCM. Stereo audio is stored LRLRLR... No padding, no alignment, no checksums. File length determines data length.
+
+Supported bit depths: 8, 16, 32 (determined by your data — SAF doesn't enforce this).
+
+## Usage
+
+SAF is header-only. Copy `saf.h` into your project.
+
+In **exactly one** `.c` file, define `SAF_IMPL` before including:
+
+```c
+#define SAF_IMPL
+#include "saf.h"
+```
+
+All other files just include normally:
+
+```c
+#include "saf.h"
+```
+
+### Writing
+
+```c
+SAF_Header header = {
+    .sample_rate = 44100,
+    .channels    = 1,
+    .bit_depth   = 16,
+};
+
+int16_t *samples = /* your audio data */;
+size_t   count   = /* number of samples */;
+
+SAF_RetCode ret = saf_write("audio.saf", header, samples, count);
+if (ret != SAF_OK)
+    fprintf(stderr, "Error: %s\n", saf_strerror(ret));
+```
+
+### Reading
+
+```c
+SAF_Header header;
+void      *samples     = NULL;
+size_t     sample_count = 0;
+
+SAF_RetCode ret = saf_read("audio.saf", &header, &samples, &sample_count);
+if (ret != SAF_OK)
+    fprintf(stderr, "Error: %s\n", saf_strerror(ret));
+
+int16_t *pcm = (int16_t *)samples;
+/* use pcm... */
+
+saf_free(&samples);
+```
+
+The library allocates the sample buffer. Always free with `saf_free` — never `free()` directly, in case the implementation changes.
+
+## API
+
+```c
+// Write audio data to a .saf file
+SAF_RetCode saf_write(const char *filename, SAF_Header header, const void *samples, size_t sample_count);
+
+// Read a .saf file — allocates sample buffer, caller must saf_free()
+SAF_RetCode saf_read(const char *filename, SAF_Header *header, void **samples, size_t *sample_count);
+
+// Free a buffer allocated by saf_read — nulls the pointer
+void saf_free(void **samples);
+
+// Return human-readable string for a return code
+const char *saf_strerror(SAF_RetCode code);
+```
+
+### Return Codes
+
+| Code            | Meaning                  |
+| --------------- | ------------------------ |
+| `SAF_OK`        | Success                  |
+| `SAF_ERR_OPEN`  | Failed to open file      |
+| `SAF_ERR_WRITE` | Failed to write file     |
+| `SAF_ERR_READ`  | Failed to read file      |
+| `SAF_ERR_MEM`   | Memory allocation failed |
+
+## Building the Test
+
+```bash
+make        # build and run test
+make clean  # clean artifacts
+```
+
+Requires GCC and `libm`.
+
+## Portability
+
+SAF manually serializes header fields byte-by-byte, so it is endian-safe and makes no assumptions about struct layout or compiler padding. Tested on Linux (GCC, Clang). Should work on any C99-compliant compiler.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

saf.h

@@ -5,6 +5,11 @@
 #include <stdio.h>
 #include <stdlib.h>
 
+#define SAF_VERSION_MAJOR 1
+#define SAF_VERSION_MINOR 0
+#define SAF_VERSION_PATCH 0
+#define SAF_VERSION "1.0.0"
+
 typedef struct saf_header
 {
     uint32_t sample_rate;
@@ -24,6 +29,7 @@ typedef enum saf_return_codes
 SAF_RetCode saf_write(const char *filename, SAF_Header header, const void *samples, size_t sample_count);
 SAF_RetCode saf_read(const char *filename, SAF_Header *header, void **samples, size_t *sample_count);
 void saf_free(void **samples);
+const char *saf_strerror(SAF_RetCode code);
 
 #ifdef SAF_IMPL