Metadata-Version: 2.1
Name: audius-py
Version: 0.1.3
Summary: Interact with the Audius platform in Python and the terminal
Home-page: https://github.com/unparalleled-js/audius-py
Author: Juliya Smith <juliya@juliyasmith.com>
Author-email: juliya@juliyasmith.com
License: Apache-2.0
Keywords: audius
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Requires-Python: >=3.9,<4
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests (<3,>=2.28.2)
Requires-Dist: click (<9,>=8.1.3)
Requires-Dist: tqdm (<5,>=4.65.0)
Requires-Dist: python-vlc (<4,>=3.0.18121)
Provides-Extra: dev
Requires-Dist: pytest (>=7.0) ; extra == 'dev'
Requires-Dist: black (>=23.1.0) ; extra == 'dev'
Requires-Dist: mypy (<2,>=1.0) ; extra == 'dev'
Requires-Dist: types-requests ; extra == 'dev'
Requires-Dist: types-setuptools ; extra == 'dev'
Requires-Dist: flake8 (>=5.0.4) ; extra == 'dev'
Requires-Dist: isort (>=5.10.1) ; extra == 'dev'
Requires-Dist: mdformat (>=0.7.16) ; extra == 'dev'
Requires-Dist: mdformat-gfm (>=0.3.5) ; extra == 'dev'
Requires-Dist: mdformat-frontmatter (>=0.4.1) ; extra == 'dev'
Requires-Dist: Sphinx (<4,>=3.4.3) ; extra == 'dev'
Requires-Dist: sphinx-rtd-theme (<1,>=0.1.9) ; extra == 'dev'
Requires-Dist: towncrier (<20,>=19.2.0) ; extra == 'dev'
Requires-Dist: setuptools ; extra == 'dev'
Requires-Dist: setuptools-scm ; extra == 'dev'
Requires-Dist: wheel ; extra == 'dev'
Requires-Dist: twine (==3.8) ; extra == 'dev'
Provides-Extra: doc
Requires-Dist: Sphinx (<4,>=3.4.3) ; extra == 'doc'
Requires-Dist: sphinx-rtd-theme (<1,>=0.1.9) ; extra == 'doc'
Requires-Dist: towncrier (<20,>=19.2.0) ; extra == 'doc'
Provides-Extra: lint
Requires-Dist: black (>=23.1.0) ; extra == 'lint'
Requires-Dist: mypy (<2,>=1.0) ; extra == 'lint'
Requires-Dist: types-requests ; extra == 'lint'
Requires-Dist: types-setuptools ; extra == 'lint'
Requires-Dist: flake8 (>=5.0.4) ; extra == 'lint'
Requires-Dist: isort (>=5.10.1) ; extra == 'lint'
Requires-Dist: mdformat (>=0.7.16) ; extra == 'lint'
Requires-Dist: mdformat-gfm (>=0.3.5) ; extra == 'lint'
Requires-Dist: mdformat-frontmatter (>=0.4.1) ; extra == 'lint'
Provides-Extra: release
Requires-Dist: setuptools ; extra == 'release'
Requires-Dist: setuptools-scm ; extra == 'release'
Requires-Dist: wheel ; extra == 'release'
Requires-Dist: twine (==3.8) ; extra == 'release'
Provides-Extra: test
Requires-Dist: pytest (>=7.0) ; extra == 'test'

# audius-py

A Python SDK and CLI for the Audius Platform.

## Installation

From pip:

```shell
pip install audius-py
```

From source (from the root project directory):

```shell
pip install .
```

**NOTE**: In order to user the media player functionality of the SDK, you must have [VLC media player](https://www.videolan.org/vlc/) installed.

## Quick Usage

To create an `audius` SDK instance, do:

```python
from audius.sdk import Audius

audius = Audius()
```

It is recommended that you set a custom app name (the default is `audius-py`).
One way to do this is via an environment variable:

```shell
export AUDIUS_APP_NAME="My_Audius_App"
```

Then, when you create an Audius SDK object, it will automatically use this value instead.

You can also specify an app name (and other configuration) when creating the SDK, like:

```python
from audius.config import Config
from audius.sdk import Audius

config = Config(app_name="my_app")
sdk = Audius(config=config)
```

Another example config value is the host, e.g.:

```shell
export AUDIUS_HOST_NAME="https://audius.example.com"
```

or:

```python
from audius.config import Config

Config(host="https://audius.exmaple.com")
```

If you don't specify a host, `audius-py` will select a random host from the list of known hosts to the Audius app.
To see all available hosts, run the following command:

```shell
audius hosts
```

### CLI

See all commands by doing:

```shell
audius --help
```

This guide will show how to stream one of the top songs on Audius directly into your terminal.
First, browse top artists using the CLI:

```shell
audius users top
```

It should show output like this:

```shell
1: Zedd (id=XlJby)
2: Skrillex (id=eAZl3)
3: Aluna (id=5j9VM)
4: kennybeats (id=DrZwG)
5: trillsammy (id=NzMW8)
6: ODESZA (id=2oNg1)
7: noodles (id=b9w8J)
8: kayzo (id=LMdyZ)
9: Disclosure (id=E2O1R)
10: Fat Nick (id=oGKZd)
```

Next, select one of the user IDs by copying it and using it in the following command:

```shell
audius users tracks eAZl3
```

It should output track information like this:

```shell
Track: Kliptown Empyrean (id=G0wyE)
```

Finally, play the track by using its ID in the following command:

```shell
audius tracks play G0wyE
```

The song should now be streaming into your terminal!
And if you really enjoy the track, you can download it by doing:

```shell
audius tracks download G0wyE song.mp3
```

### Python SDK

Use the Python SDK directly:

```python
from audius.sdk import Audius

sdk = Audius(app="my_app")
for artist in sdk.users.top():
    print(artist["name"])
```


