# 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"])
```
Raw data
{
"_id": null,
"home_page": "https://github.com/unparalleled-js/audius-py",
"name": "audius-py",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.9",
"maintainer_email": null,
"keywords": "audius",
"author": "Juliya Smith <juliya@juliyasmith.com>",
"author_email": "juliya@juliyasmith.com",
"download_url": "https://files.pythonhosted.org/packages/94/2a/41ad6bcb43130d1b5b0df60d53c385690bb845f624451c4af0cb78834e74/audius-py-0.1.6.tar.gz",
"platform": null,
"description": "# audius-py\n\nA Python SDK and CLI for the Audius Platform.\n\n## Installation\n\nFrom pip:\n\n```shell\npip install audius-py\n```\n\nFrom source (from the root project directory):\n\n```shell\npip install .\n```\n\n**NOTE**: In order to user the media player functionality of the SDK, you must have [VLC media player](https://www.videolan.org/vlc/) installed.\n\n## Quick Usage\n\nPlay a random song from Audius!\n\n```shell\naudius play\n```\n\n## In-Depth Usage\n\nTo create an `audius` SDK instance, do:\n\n```python\nfrom audius import Audius\n\naudius = Audius()\n```\n\nIt is recommended that you set a custom app name (the default is `audius-py`).\n\n```python\naudius = Audius(\"My_Audius_App\")\n```\n\nYou can also use an environment:\n\n```shell\nexport AUDIUS_APP_NAME=\"My_Audius_App\"\n```\n\nAnd when you initialize without any arguments like `Audius()`, it will use the environment variable.\n\nYou can also specify a `Config` option where you can set more config than `app_name`:\n\n```python\nfrom audius.config import Config\nfrom audius.sdk import Audius\n\nconfig = Config(app_name=\"my_app\", host=\"https://audius.example.com\")\nsdk = Audius(config)\n```\n\nThe Audius host name is also configurable as an environment variable:\n\n```shell\nexport AUDIUS_HOST_NAME=\"https://audius.example.com\"\n```\n\nor:\n\n```python\nfrom audius.config import Config\n\nConfig(host=\"https://audius.exmaple.com\")\n```\n\nIf you don't specify a host, `audius-py` will select a random host from the list of known hosts to the Audius app.\nTo see all available hosts, run the following command:\n\n```shell\naudius hosts\n```\n\n### CLI\n\nSee all commands by doing:\n\n```shell\naudius --help\n```\n\nThis guide will show how to stream one of the top songs on Audius directly into your terminal.\nFirst, browse top artists using the CLI:\n\n```shell\naudius users top\n```\n\nIt should show output like this:\n\n```shell\n1: Zedd (id=XlJby)\n2: Skrillex (id=eAZl3)\n3: Aluna (id=5j9VM)\n4: kennybeats (id=DrZwG)\n5: trillsammy (id=NzMW8)\n6: ODESZA (id=2oNg1)\n7: noodles (id=b9w8J)\n8: kayzo (id=LMdyZ)\n9: Disclosure (id=E2O1R)\n10: Fat Nick (id=oGKZd)\n```\n\nNext, select one of the user IDs by copying it and using it in the following command:\n\n```shell\naudius users tracks eAZl3\n```\n\nIt should output track information like this:\n\n```shell\nTrack: Kliptown Empyrean (id=G0wyE)\n```\n\nFinally, play the track by using its ID in the following command:\n\n```shell\naudius tracks play G0wyE\n```\n\nThe song should now be streaming into your terminal!\nAnd if you really enjoy the track, you can download it by doing:\n\n```shell\naudius tracks download G0wyE song.mp3\n```\n\nBy default, `audius-py` tries to find the best player.\nHowever, specify your player of choice using the `--player` flag:\n\n```shell\naudius tracks play G0wyE --player vlc\n```\n\n### Python SDK\n\nUse the Python SDK directly:\n\n```python\nfrom audius.sdk import Audius\n\nsdk = Audius(app=\"my_app\")\nfor artist in sdk.users.top():\n print(artist[\"name\"])\n```\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Interact with the Audius platform in Python and the terminal",
"version": "0.1.6",
"project_urls": {
"Homepage": "https://github.com/unparalleled-js/audius-py"
},
"split_keywords": [
"audius"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "434ed4fac1812dec7a00425b7ea217ba7ee460c6d3c4432afac1bbfe10f6b966",
"md5": "8b59eadaf88aa4933dd05d3d4eb73fce",
"sha256": "75ddf93b9ca1aea044d86a2ec625bf7ff8a2470be72650680c033cbf9c4a2c91"
},
"downloads": -1,
"filename": "audius_py-0.1.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8b59eadaf88aa4933dd05d3d4eb73fce",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.9",
"size": 19092,
"upload_time": "2025-02-04T01:39:07",
"upload_time_iso_8601": "2025-02-04T01:39:07.973493Z",
"url": "https://files.pythonhosted.org/packages/43/4e/d4fac1812dec7a00425b7ea217ba7ee460c6d3c4432afac1bbfe10f6b966/audius_py-0.1.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "942a41ad6bcb43130d1b5b0df60d53c385690bb845f624451c4af0cb78834e74",
"md5": "78805ec8c4383668340f21a05e63afca",
"sha256": "7526965871ad388e4985c0d473db5b7e5e493965a56cdd39720e9419d1e89ca8"
},
"downloads": -1,
"filename": "audius-py-0.1.6.tar.gz",
"has_sig": false,
"md5_digest": "78805ec8c4383668340f21a05e63afca",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.9",
"size": 18706,
"upload_time": "2025-02-04T01:39:10",
"upload_time_iso_8601": "2025-02-04T01:39:10.181788Z",
"url": "https://files.pythonhosted.org/packages/94/2a/41ad6bcb43130d1b5b0df60d53c385690bb845f624451c4af0cb78834e74/audius-py-0.1.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-04 01:39:10",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "unparalleled-js",
"github_project": "audius-py",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "audius-py"
}
JSON
