From 7b5333284364fd7dc8f3e91281225566188332e7 Mon Sep 17 00:00:00 2001
From: Yuto Takano <moa17stock@gmail.com>
Date: Fri, 14 Feb 2025 18:58:17 +0100
Subject: [PATCH] Add usage, license, and development information to README

---
 README.md | 67 +++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 63 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index ffb04ec..05e9705 100644
--- a/README.md
+++ b/README.md
@@ -1,11 +1,70 @@
-# opus
+# opus: Haskell Bindings to libopus
 
+> This is an active fork of previous work at
+> [alios/opus](https://github.com/alios/opus)
+> with permission granted from the original author to publish the package/code
+> under the same name.
 
-## get test files 
+Xiph.Org Foundation's Opus Audio codec is a widely used audio codec for VoIP and
+streaming. `libopus` is the reference implementation of an encoder and decoder
+for this codec, and is available to be used via various package managers
+[under the BSD-3 license](https://opus-codec.org/license/).
+
+This Haskell package provides bindings to `libopus`'s encoding and decoding
+functionality. It is continuously tested against the official audio vectors in
+the project CI (on GitHub).
+
+The package also provides Conduit functions for encoding and decoding, for easy
+use in streaming scenarios.
+
+## Usage
+
+1. Add `opus` to your cabal/stack project dependencies
+2. Install `libopus` and `pkg-config` (used for finding where libopus is):
+   1. **On Windows**: Run the following commands in your MSYS2 environment:
+      ```
+      pacman -S mingw64/mingw-w64-x86_64-pkg-config
+      pacman -S mingw64/mingw-w64-x86_64-opus
+      ```
+      If you do not know where your MSYS2 environment is, but you installed
+      the Haskell toolchain using GHCup, try:
+      ```
+      ghcup run -m -- pacman -S mingw64/mingw-w64-x86_64-pkg-config
+      ghcup run -m -- pacman -S mingw64/mingw-w64-x86_64-opus
+      ```
+   2. **On MacOS**: Run the following commands:
+      ```
+      brew install opus
+      ```
+   3. **On Ubuntu/Debian**: Run the following commands:
+      ```
+      apt-get install pkg-config
+      apt-get install libopus-dev
+      ```
+3. Import and get going! For example, import `Codec.Audio.Opus.Encoder` to use
+   the `opusEncoderCreate` and `opusEncode` functions.
+
+## Development
+
+To develop locally, you will need the `pkg-config` (pre-installed on Mac) and
+`libopus` system packages, as described above.
+
+To run tests locally, you will also need the Opus test vectors available within
+a directory called `opus_newvectors`. The following command will do just that:
 
 ```
-$ curl -OL https://opus-codec.org/docs/opus_testvectors-rfc8251.tar.gz
+curl -L https://opus-codec.org/static/testvectors/opus_testvectors-rfc8251.tar.gz | tar -xz
 ```
 
+## License
+
+`test/opus_compare.c` was taken as-is from Xiph.Org Foundation under the BSD-3
+license.
+
+This project as a whole is licensed under the BSD-3 license. Please see the
+LICENSE file for more information.
+
+Copyright (c) 2018 Markus Barenhoff
+Copyright (c) 2021-2022 Yuto Takano
+Copyright (c) 2025-PRESENT Haskell Opus Library Contributors
 
-test/opus_compare.c is taken as-is from Xiph.Org Foundation under the BSD-3 license.