README.md
1[](https://github.com/ramsayleung/rspotify/actions)
2[](https://github.com/ramsayleung/rspotify/blob/master/LICENSE)
3[](https://crates.io/crates/rspotify)
4[](https://docs.rs/crate/rspotify/)
5
6# Rspotify - a Rust client for The Spotify Web API
7
8## Disclaimer
9
10This crate is heavily inspired by [spotipy](https://github.com/plamere/spotipy)- A spotify api wrapper implemented in Python
11
12## Description
13
14Rspotify is a lightweight wrapper for the [Spotify Web API](https://developer.spotify.com/web-api/) It includes helper functions for
15**all Spotify's endpoints**, such as fetching metadata (search and look-up of albums, artists, tracks, playlists, new releases) and user's information (follow
16users, artists and playlists, and saved tracks management).
17
18## Features
19
20*rspotify* supports all of the features of the Spotify Web API including access to all end points, and support for user authorization, notes that before accessing to any end points, you need to be authorized. For details on the capabilities you are encouraged to review the [Spotify Web Endpoint Reference](https://developer.spotify.com/web-api/endpoint-reference/) documentation.
21
22Nowaday, thanks to [`reqwest`](https://docs.rs/reqwest/0.10.1/reqwest/#proxies), `rspotify` now supports system proxy by default. `Reqwest` System proxies look in environment variables to set HTTP or HTTPS proxies. `HTTP_PROXY` or `http_proxy` provide http proxies for http connections while `HTTPS_PROXY` or `https_proxy` provide HTTPS proxies for HTTPS connections.(~~Notes that `reqwest` system proxy doesn't support socks proxy for now,~~ check [this issue](https://github.com/seanmonstar/reqwest/issues/790) for more details)
23
24## Installation
25
26``` shell
27cargo install rspotify
28```
29
30Or you could get it from [github](https://github.com/samrayleung/rspotify)
31
32## Getting Started
33
34### Authorization
35
36Since all methods require user authorization now, you will need to generate an authorization token that indicates that the user has granted permission for your application to perform the given task. You will need to register your app to get the credentials necessary to make authorized calls.
37
38Even if your script does not have an accessible URL you need to specify one when registering your application where the spotify authentication API will redirect to after successful login. The URL doesn't need to work or be accessible, you can specify "http://localhost/", after successful login you just need to copy the "http://localhost/?code=..." URL from your browser and paste it to the console where your application is running. For example:
39
40
41In order to help other developers to get used to `rspotify`, I registerd a Spotify account with temporary email. Your guys could test `rspotify` with this account's `CLIENT_ID` and `CLIENT_SECRET`, check [.env file](./.env) for more details.
42
43### Examples
44
45If you have a use case you are interested in, you could check the
46[examples](./examples), which has all kinds of detailed examples. For example,
47If you want to get recently played history, you could check
48[current_user_recently_played](./examples/current_user_recently_played.rs). This is
49the example code:
50
51``` toml
52[dependencies]
53rspotify = { version = "0.9"}
54tokio = { version = "0.2", features = ["full"] }
55```
56
57``` rust
58extern crate rspotify;
59
60use rspotify::client::Spotify;
61use rspotify::oauth2::SpotifyClientCredentials;
62use rspotify::senum::Country;
63
64#[tokio::main]
65async fn main() {
66 // Set client_id and client_secret in .env file or
67 // export CLIENT_ID="your client_id"
68 // export CLIENT_SECRET="secret"
69 let client_credential = SpotifyClientCredentials::default().build();
70
71 // Or set client_id and client_secret explictly
72 // let client_credential = SpotifyClientCredentials::default()
73 // .client_id("this-is-my-client-id")
74 // .client_secret("this-is-my-client-secret")
75 // .build();
76 let spotify = Spotify::default()
77 .client_credentials_manager(client_credential)
78 .build();
79 let birdy_uri = "spotify:artist:2WX2uTcsvV5OnS0inACecP";
80 let tracks = spotify
81 .artist_top_tracks(birdy_uri, Country::UnitedStates)
82 .await;
83 println!("{:?}", tracks.unwrap());
84}
85```
86
87### Blocking API example
88There is an optional "blocking" client API that can be enabled:
89
90``` toml
91[dependencies]
92rspotify = { version = "0.9", features=["blocking"]}
93```
94
95``` rust
96extern crate rspotify;
97
98use rspotify::blocking::client::Spotify;
99use rspotify::blocking::oauth2::SpotifyClientCredentials;
100use rspotify::senum::Country;
101
102fn main() {
103 let client_credential = SpotifyClientCredentials::default().build();
104 let spotify = Spotify::default()
105 .client_credentials_manager(client_credential)
106 .build();
107 let birdy_uri = "spotify:artist:2WX2uTcsvV5OnS0inACecP";
108 let tracks = spotify.artist_top_tracks(birdy_uri, Country::UnitedStates);
109 println!("{:?}", tracks.unwrap());
110}
111```
112
113## Examples
114
115+ Albums:
116 - [Get an Album](./examples/album.rs)
117 - [Get An Album's Tracks](./examples/album_tracks.rs)
118 - [Get several Albums](./examples/albums.rs)
119 - [Get current user's saved albums](./examples/current_user_saved_albums.rs)
120 - [Add one or more albums to the current user](./examples/current_user_saved_albums_add.rs)
121 - [Remove one or more albums from the current user](./examples/current_user_saved_albums_delete.rs)
122 - [Check current user's saved album](./examples/current_user_saved_albums_contains.rs)
123
124+ Artists:
125 - [Get an Artist](./examples/artist.rs)
126 - [Get an Artist's Albums](./examples/artists_albums.rs)
127 - [Get an Artist's Top Tracks](./examples/artist_top_tracks.rs)
128 - [Get an Artist's Related Artists](./examples/artist_related_artists.rs)
129 - [Get Several Artists](./examples/artists.rs)
130 - [Get current user's followed artists](./examples/current_user_followed_artists.rs)
131 - [Get current user's top artists](./examples/current_user_top_artists.rs)
132 - [Current user follow one or more artists](./examples/user_follow_artists.rs)
133 - [Current user unfollow one or more artists](./examples/user_unfollow_artists.rs)
134 - [Check current user follow artists](./examples/user_artist_check_follow.rs)
135
136+ Browse:
137 - [Get a List of Categories](./examples/categories.rs)
138
139+ Track:
140 - [Get a Track](./examples/track.rs)
141 - [Get several tracks](./examples/tracks.rs)
142 - [Get current user's currently playing track](./examples/current_user_playing_track.rs)
143 - [Get current user's saved tracks](./examples/current_user_saved_tracks.rs)
144 - [Remove current user's saved tracks](./examples/current_user_saved_tracks_delete.rs)
145 - [Check current user's saved tracks](./examples/current_user_saved_tracks_contains.rs)
146 - [Current user add tracks](./examples/current_user_saved_tracks_add.rs)
147 - [Get current user's top tracks](./examples/current_user_top_tracks.rs)
148 - [Get current user's recently played tracks](./examples/current_user_recently_played.rs)
149 - [Get audio features for a track](./examples/audio_features.rs)
150 - [Get audio features for several tracks](./examples/audios_features.rs)
151 - [Get audio analysis for a track](./examples/audio_analysis.rs)
152
153+ Player
154 - [Get current user's available devices](./examples/device.rs)
155 - [Get information about current user's current playback](./examples/current_playback.rs)
156 - [Get current user's currently playing track](./examples/current_playing.rs)
157 - [Transfer current user's playback](./examples/transfer_playback.rs)
158 - [Start/Resume current user’s playback](./examples/start_playback.rs)
159 - [Pause current user's playback](./examples/pause_playback.rs)
160 - [Skip current user's playback to next track](./examples/next_track.rs)
161 - [Skip current user's playback to previous track](./examples/previous_track.rs)
162 - [Seek to position in currently playing track](./examples/seek_track.rs)
163 - [Set repeat mode on current user's playback](./examples/repeat.rs)
164 - [Set volume for current user's playback](./examples/volume.rs)
165 - [Toggle shuffle for current user's playback](./examples/shuffle.rs)
166 - [Add an item to the end of current user's playback queue](#)
167
168+ Show:
169 - [Save shows for current user](./examples/save_shows.rs)
170 - [Get a list of saved shows](./examples/save_shows.rs)
171 - [Get a show](./examples/get_a_show.rs)
172 - [Get seversal shows](./examples/get_several_shows.rs)
173 - [Check current user's saved shows](./examples/check_users_saved_shows.rs)
174 - [Remove current user's saved shows](./examples/remove_users_saved_shows.rs)
175
176+ Episodes
177 - [Get a show's episodes](./examples/get_shows_episodes.rs)
178 - [Get an Episode](./examples/get_an_episode.rs)
179 - [Get seversal episodes](./examples/get_several_episodes.rs)
180
181+ Search:
182 - [Search Item](./examples/search.rs)
183 - [Search Artist](./examples/search.rs)
184 - [Search Album](./examples/search.rs)
185 - [Search Track](./examples/search.rs)
186 - [Search Playlist](./examples/search.rs)
187 - [Search Show](./examples/search.rs)
188 - [Search Episode](./examples/search.rs)
189
190+ User:
191 - [Get user's profile](./examples/user.rs)
192 - [Get current user's profile](./examples/me.rs)
193 - [Current User follow users](./examples/user_follow_users.rs)
194 - [Current User unfollow users](./examples/user_unfollow_users.rs)
195
196
197+ Playlist:
198 - [Get a Playlist](./examples/playlist.rs)
199 - [Get a List of a User's Playlist](./examples/user_playlists.rs)
200 - [Get a Playlists's tracks](./examples/user_playlist_tracks.rs)
201 - [Creates a playlist for a user](./examples/user_playlist_create.rs)
202 - [Change playlist's details](./examples/user_playlist_change_detail.rs)
203 - [Unfollowsa playlist for a user](./examples/user_playlist_unfollow.rs)
204 - [Adds tracks to a playlist](./examples/user_playlist_add_tracks.rs)
205 - [Replace all tracks in a playlist](./examples/user_playlist_replace_tracks.rs)
206 - [Reorder tracks in a playlist](./examples/user_playlist_recorder_tracks.rs)
207 - [Remove tracks from a playlist](./examples/user_playlist_remove_all_occurrences_of_tracks.rs)
208 - [Remove specific tracks from a playlist](./examples/user_playlist_remove_specific_occurrenes_of_tracks)
209 - [User follow a playlist](./examples/user_playlist_follow_playlist.rs)
210 - [Check user following playlist](./examples/user_playlist_check_follow.rs)
211 - [Get a list of Spotify featured playlists](./examples/featured_playlists.rs)
212
213+ Misc
214 - [Get list new releases](./examples/new_releases.rs)
215 - [Get list categories](./examples/categories.rs)
216 - [get recommendtions](./examples/recommendations.rs)
217
218## API Documentation
219
220For more API information, you could check [rspotify Api documentation](https://docs.rs/crate/rspotify)
221
222## CHANGELOG
223
224Please see the [CHANGELOG](./CHANGELOG.md) for a release history.
225
226## Contribution
227
228If you find any problem or have suggestions about this crate, please submit an
229issue. Moreover, any pull request ,code review and feedback are welcome.
230
231## License
232
233[MIT](./LICENSE)
234
){kind=link}
){kind=link}
){kind=link}
