sunk/
lib.rs

1#![warn(missing_docs)]
2#![doc(html_root_url = "https://docs.rs/sunk/0.1.2")]
3
4//! # sunk
5//!
6//! `sunk` provides natural Rust bindings to the [Subsonic] music server API.
7//! Many other popular music servers, such as Libresonic and Airsonic, also use
8//! the Subsonic API, so this crate can stretch far beyond just Subsonic.
9//!
10//! [Subsonic]: http://www.subsonic.org/pages/index.jsp
11//!
12//! # Basic usage
13//!
14//! ```no_run
15//! extern crate sunk;
16//! use sunk::song::Song;
17//! use sunk::{Album, Artist, Client, Streamable};
18//!
19//! # fn run() -> sunk::Result<()> {
20//! let site = "http://subsonic.example.com";
21//! let username = "admin";
22//! let password = "hunter2";
23//!
24//! let client = Client::new(site, username, password)?;
25//!
26//! let random_songs = Song::random(&client, 20)?;
27//! for mut song in random_songs {
28//!     song.set_max_bit_rate(320);
29//!     let bytes = song.stream(&client)?;
30//!     // Use another library to stream the `bytes`!
31//! }
32//! # Ok(())
33//! # }
34//! # fn main() { }
35//! ```
36//!
37//! # Philosophy
38//!
39//! The fundamental principle behind the way `sunk` works is to be able to pivot
40//! on everything. If you have something returned from a query, you should be
41//! able to investigate that object more deeply. This is modelled after what
42//! you'd typically expect from mobile or web clients.
43//!
44//! An example can be seen below:
45//!
46//! ```no_run
47//! # extern crate sunk;
48//! # use sunk::{Client, Album, Artist, Streamable};
49//! # use sunk::song::Song;
50//! # fn run() -> sunk::Result<()> {
51//! # let site = "http://subsonic.example.com";
52//! # let username = "admin";
53//! # let password = "hunter2";
54//! let client = Client::new(site, username, password)?;
55//!
56//! // I want to play some <insert artist here>.
57//! let an_artist = Artist::get(&client, 20)?;
58//! let artist_info = an_artist.info(&client)?;
59//! let artists_albums = an_artist.albums(&client)?;
60//!
61//! // I love this album. Let's download it.
62//! let ref fav_album = artists_albums[0];
63//! let album_info_and_similar = fav_album.info(&client)?;
64//! let album_songs = fav_album.songs(&client)?;
65//!
66//! use std::fs::File;
67//! use std::io::Write;
68//! for song in &album_songs {
69//!     let bytes = song.download(&client)?;
70//!     let mut file =
71//!         File::create(song.title.clone() + "." + song.encoding())?;
72//!     file.write(&bytes)?;
73//! }
74//!
75//! // I want to find stuff like this song.
76//! let ref this_is_good = album_songs[6];
77//! let similar = this_is_good.similar(&client, 10)?;
78//! # Ok(())
79//! # }
80//! # fn main() { }
81//! ```
82//!
83//! This has the result of many methods requiring an active connection to a
84//! `Client` to fetch more information.
85//!
86//! # Debugging
87//!
88//! The crate uses [`log`] as its debugging backend. If your crate uses log,
89//! you'll see output from `sunk` at any information level starting at warning
90//! (for critical processes) or info (for most other processes).
91//!
92//! [`log`]: https://doc.rust-lang.org/log/log/index.html
93//!
94//! # Development
95//!
96//! The crate is still under active development. Methods and paths may change,
97//! and many have not been tested due to the requirement of having full access
98//! to a Subsonic instance. See the repository for any changes and development
99//! status.
100//!
101//! Bug reports and broken features are encouraged to be reported! **If
102//! something does not work as reported, it's probably broken.**
103
104#[macro_use]
105extern crate failure;
106#[macro_use]
107extern crate log;
108extern crate md5;
109extern crate rand;
110extern crate reqwest;
111extern crate serde;
112#[macro_use]
113extern crate serde_derive;
114extern crate serde_json;
115
116#[macro_use]
117mod macros;
118mod client;
119mod error;
120
121mod collections;
122mod media;
123
124mod annotate;
125mod jukebox;
126mod query;
127mod response;
128pub mod search;
129mod user;
130mod version;
131
132#[cfg(test)]
133mod test_util;
134
135pub use self::client::Client;
136pub use self::collections::Playlist;
137pub use self::collections::{Album, AlbumInfo, ListType};
138pub use self::collections::{Artist, ArtistInfo};
139pub use self::collections::{Genre, MusicFolder};
140pub use self::error::{ApiError, Error, Result, UrlError};
141pub use self::jukebox::{Jukebox, JukeboxPlaylist, JukeboxStatus};
142pub use self::media::{podcast, song, video};
143pub use self::media::{Hls, HlsPlaylist, Media, NowPlaying, RadioStation, Streamable};
144pub use self::user::{User, UserBuilder};
145pub use self::version::Version;
146
147use self::song::{Lyrics, RandomSongs, Song};
148use self::video::Video;
sunk/lib.rs

sunk/
lib.rs
