From b07bb55ea83d12cbb7cba06980dcf03d4fbca5ee Mon Sep 17 00:00:00 2001 From: Jay Malhotra Date: Thu, 4 Sep 2025 22:15:33 +0100 Subject: [PATCH] docs: Document examples Document the process for running the examples. This was fairly non-obvious and I spent a fair bit of time trying and failing to get a client credentials token to work before finding in some discussion that this is known not to work. The wiki mentions using the oauth example as a way to get a token and I think that is likely to be the best way to get a token for the purposes of running the examples too. --- examples/README.md | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 examples/README.md diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 00000000..9a5e794b --- /dev/null +++ b/examples/README.md @@ -0,0 +1,36 @@ +# Examples + +This folder contains examples of how to use the `librespot` library for various purposes. + +## How to run the examples + +In general, to invoke an example, clone down the repo and use `cargo` as follows: + +``` +cargo run --example [filename] +``` + +in which `filename` is the file name of the example, for instance `get_token` or `play`. + +### Acquiring an access token + +Most examples require an access token as the first positional argument. **Note that an access token +gained by the client credentials flow will not work**. `librespot-oauth` provides a utility to +acquire an access token using an OAuth flow, which will be able to run the examples. To invoke this, +run: + +``` +cargo run --package librespot-oauth --example oauth_sync +``` + +A browser window will open and prompt you to authorize with Spotify. Once done, take the +`access_token` property from the dumped object response and proceed to use it in examples. You may +find it convenient to save it in a shell variable like `$ACCESS_TOKEN`. + +Once you have obtained the token you can proceed to run the example. Check each individual +file to see what arguments are expected. As a demonstration, here is how to invoke the `play` +example to play a song -- the second argument is the URI of the track to play. + +``` +cargo run --example play "$ACCESS_TOKEN" 2WUy2Uywcj5cP0IXQagO3z +``` \ No newline at end of file