Metadata-Version: 2.1
Name: audius-py
Version: 0.1.6
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
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
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.9,<4
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests<3,>=2.32.3
Requires-Dist: cyclopts<4,>=3.4.1
Requires-Dist: tqdm<5,>=4.67.1
Requires-Dist: afplay-py<0.3,>=0.2.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-mock; extra == "dev"
Requires-Dist: black>=24.10.0; extra == "dev"
Requires-Dist: mypy<2,>=1.14.1; extra == "dev"
Requires-Dist: types-requests; extra == "dev"
Requires-Dist: types-setuptools; extra == "dev"
Requires-Dist: flake8>=7.1.1; extra == "dev"
Requires-Dist: flake8-type-checking; extra == "dev"
Requires-Dist: isort>=5.13.2; extra == "dev"
Requires-Dist: mdformat>=0.7.21; extra == "dev"
Requires-Dist: mdformat-gfm>=0.3.5; extra == "dev"
Requires-Dist: mdformat-frontmatter>=0.4.1; extra == "dev"
Requires-Dist: Sphinx<8,>=7.473; extra == "dev"
Requires-Dist: sphinx-rtd-theme<3,>=2.0.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"
Requires-Dist: python-vlc<4,>=3.0.18121; extra == "dev"
Provides-Extra: doc
Requires-Dist: Sphinx<8,>=7.473; extra == "doc"
Requires-Dist: sphinx-rtd-theme<3,>=2.0.0; extra == "doc"
Provides-Extra: lint
Requires-Dist: black>=24.10.0; extra == "lint"
Requires-Dist: mypy<2,>=1.14.1; extra == "lint"
Requires-Dist: types-requests; extra == "lint"
Requires-Dist: types-setuptools; extra == "lint"
Requires-Dist: flake8>=7.1.1; extra == "lint"
Requires-Dist: flake8-type-checking; extra == "lint"
Requires-Dist: isort>=5.13.2; extra == "lint"
Requires-Dist: mdformat>=0.7.21; 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"
Requires-Dist: pytest-mock; extra == "test"
Provides-Extra: vlc
Requires-Dist: python-vlc<4,>=3.0.18121; extra == "vlc"

# 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

Play a random song from Audius!

```shell
audius play
```

## In-Depth Usage

To create an `audius` SDK instance, do:

```python
from audius import Audius

audius = Audius()
```

It is recommended that you set a custom app name (the default is `audius-py`).

```python
audius = Audius("My_Audius_App")
```

You can also use an environment:

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

And when you initialize without any arguments like `Audius()`, it will use the environment variable.

You can also specify a `Config` option where you can set more config than `app_name`:

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

config = Config(app_name="my_app", host="https://audius.example.com")
sdk = Audius(config)
```

The Audius host name is also configurable as an environment variable:

```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
```

By default, `audius-py` tries to find the best player.
However, specify your player of choice using the `--player` flag:

```shell
audius tracks play G0wyE --player vlc
```

### 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"])
```
