From 559a310d36204e069327c1638511cecdf331ce1d Mon Sep 17 00:00:00 2001
From: Nils Pukropp <nils@narl.io>
Date: Sun, 22 Mar 2026 12:07:55 +0100
Subject: [PATCH] docs: update README with async builder and JSON parsing
 examples

---
 README.md | 71 +++++++++++++++++++++++++++++++++++++++++++------------
 1 file changed, 56 insertions(+), 15 deletions(-)

diff --git a/README.md b/README.md
index 8cdd097..076a169 100644
--- a/README.md
+++ b/README.md
@@ -2,27 +2,68 @@
 [![Build status](https://github.com/nirusu99/ytd-rs/actions/workflows/rust.yml/badge.svg)](https://github.com/nirusu99/ytd-rs/actions)
 [![crates.io](https://img.shields.io/crates/v/ytd-rs.svg)](https://crates.io/crates/ytd-rs)
 [![docs.rs](https://docs.rs/ytd-rs/badge.svg)](https://docs.rs/ytd-rs)
-[![dependency status](https://deps.rs/repo/github/nirusu99/ytd-rs/status.svg)](https://deps.rs/repo/github/nirusu99/ytd-rs)
 
-This is a simple wrapper for [youtube-dl](https://youtube-dl.org/) in rust.
+An async, feature-rich Rust wrapper for [yt-dlp](https://github.com/yt-dlp/yt-dlp).
 
+## Features
+- **Async API**: Built on top of `tokio`.
+- **Builder Pattern**: Fluent API for configuring downloads.
+- **Structured Metadata**: Extract video info as JSON via `serde`.
+- **Custom Arguments**: Passthrough for any `yt-dlp` flag.
+
+## Prerequisites
+You must have `yt-dlp` installed and available in your `PATH`.
+
+## Usage
+
+### Simple Download
 ```rust
-use ytd_rs::{YoutubeDL, Arg};
+use ytd_rs::YtDlp;
 use std::path::PathBuf;
-use std::error::Error;
-fn main() -> Result<(), Box<dyn Error>> {
-    // youtube-dl arguments quietly run process and to format the output
-    // one doesn't take any input and is an option, the other takes the desired output format as input
-    let args = vec![Arg::new("--quiet"), Arg::new_with_arg("--output", "%(title).90s.%(ext)s")];
-    let link = "https://www.youtube.com/watch?v=uTO0KnDsVH0";
-    let path = PathBuf::from("./path/to/download/directory");
-    let ytd = YoutubeDL::new(&path, args, link)?;
 
-    // start download
-    let download = ytd.download()?;
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let ytd = YtDlp::new("https://www.youtube.com/watch?v=uTO0KnDsVH0")
+        .output_dir(PathBuf::from("./downloads"))
+        .arg("--quiet");
 
-    // print out the download path
-    println!("Your download: {}", download.output_dir().to_string_lossy());
+    let result = ytd.download().await?;
+    println!("Output: {}", result.output());
     Ok(())
 }
 ```
+
+### Extract Audio
+```rust
+use ytd_rs::YtDlp;
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    YtDlp::new("https://www.youtube.com/watch?v=uTO0KnDsVH0")
+        .extract_audio(true)
+        .audio_format("mp3")
+        .download()
+        .await?;
+    Ok(())
+}
+```
+
+### Get Video Metadata
+```rust
+use ytd_rs::YtDlp;
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let ytd = YtDlp::new("https://www.youtube.com/watch?v=uTO0KnDsVH0");
+    let infos = ytd.get_info().await?;
+    
+    for info in infos {
+        println!("Title: {}", info.title);
+        println!("Duration: {:?}", info.duration);
+    }
+    Ok(())
+}
+```
+
+## License
+MIT