Songs¶

All levels in Geometry Dash are based on different songs; either official ones, or custom songs from Newgrounds.

gd.py provides simple API for fetching and working with both of them:

client = gd.Client()

song = gd.Song.official(0, client=client)
# <Song id=0 name='Stereo Madness' author='ForeverBound'>

print(song.is_custom())  # False

song = await client.get_song(1)  # or get_ng_song for Newgrounds fetching
# <Song id=1 name='Chilled 1' author='Recoil'>

await song.download("test.mp3", with_bar=True)

Artist Info¶

class gd.ArtistInfo(*, client: Optional[Client] = None, **options)[source]¶

Class that represents info about the creator of a particular song.

to_dict() → Dict[str, Any][source]¶: Convert the entity to a dictionary.

property artist¶

Author of the song.

Type: str

property song¶

A name of the song.

Type: str

property exists¶

Whether the song exists.

Type: bool

is_scouted() → bool [source]¶: bool: Whether the artist is scouted.

is_whitelisted() → bool [source]¶: bool: Whether the artist is whitelisted.

api_allowed() → bool [source]¶: bool: Whether the external API is allowed.

is_custom() → bool [source]¶: bool: Whether the song is custom.

get_author() → gd.song.Author[source]¶: Author of the song.

property author¶: Author of the song.

async update() → None [source]¶

Update artist info.

Raises

MissingAccess – Failed to find artist info.
HTTPStatusError – Server returned error status code.
HTTPError – Failed to process the request.

attach_client(client: Optional[Client] = None) → AbstractEntityT¶

Attach client to self.

Parameters: client (Optional[gd.Client]) – Client to attach. If None or not given, will be detached.
Returns: This abstract entity.
Return type: AbstractEntity

property client¶

Client attached to this object. This checks if client is not present, and raises ClientException in that case.

Type: Client

property client_unchecked¶

Client attached to this object.

Type: Optional[Client]

detach_client() → AbstractEntityT¶

Detach client from self.

Same as calling:

self.attach_client(None)

Returns: This abstract entity.
Return type: AbstractEntity

classmethod from_dict(*data: Dict[str, Any], client: Optional[Client] = None, **kwargs) → AbstractEntityT¶: Create new entity from dictionaries in data, with client and kwargs.

classmethod from_dicts(*data: Dict[str, Any], client: Optional[Client] = None, **kwargs) → AbstractEntityT¶: Create new entity from dictionaries in data, with client and kwargs.

classmethod from_model(model: gd.model_backend.Model, *args, **kwargs) → AbstractEntityT¶: Create new entity from given model, args and kwargs.

classmethod from_models(*models: gd.model_backend.Model, **kwargs) → AbstractEntityT¶: Create new entity from given models by calling from_model with kwargs.

property hash_str¶

String used for hashing, with format <Class(ID->id)>.

Type: str

property id¶

ID of the Entity.

Type: int

update_inner(**options: Any) → AbstractEntityT¶: Update self.options with options.

Author¶

class gd.Author(*, client: Optional[Client] = None, **options)[source]¶

Class that represents an author on Newgrounds. This class is derived from AbstractEntity.

property id¶

ID of the Author.

Type: int

property link¶

URL to author’s page.

Type: URL

property name¶

Name of the author.

Type: str

get_page_songs(page: int = 0) → AsyncIterator[gd.song.Song][source]¶

Get songs on the page.

Parameters

page (int) – Page of songs to look at.

Raises

MissingAccess – Failed to find songs.
HTTPStatusError – Server returned error status code.
HTTPError – Failed to process the request.

Returns

Songs found.

Return type

AsyncIterator[Song]

get_songs(pages: Iterable[int] = range(0, 10)) → AsyncIterator[gd.song.Song][source]¶

Get songs on the pages.

Parameters

pages (Iterable[int]) – Pages of songs to look at.

Raises

MissingAccess – Failed to find songs.
HTTPStatusError – Server returned error status code.
HTTPError – Failed to process the request.

Returns

Songs found.

Return type

AsyncIterator[Song]

attach_client(client: Optional[Client] = None) → AbstractEntityT¶

Attach client to self.

Parameters: client (Optional[gd.Client]) – Client to attach. If None or not given, will be detached.
Returns: This abstract entity.
Return type: AbstractEntity

property client¶

Client attached to this object. This checks if client is not present, and raises ClientException in that case.

Type: Client

property client_unchecked¶

Client attached to this object.

Type: Optional[Client]

detach_client() → AbstractEntityT¶

Detach client from self.

Same as calling:

self.attach_client(None)

Returns: This abstract entity.
Return type: AbstractEntity

classmethod from_dict(*data: Dict[str, Any], client: Optional[Client] = None, **kwargs) → AbstractEntityT¶: Create new entity from dictionaries in data, with client and kwargs.

classmethod from_dicts(*data: Dict[str, Any], client: Optional[Client] = None, **kwargs) → AbstractEntityT¶: Create new entity from dictionaries in data, with client and kwargs.

classmethod from_model(model: gd.model_backend.Model, *args, **kwargs) → AbstractEntityT¶: Create new entity from given model, args and kwargs.

classmethod from_models(*models: gd.model_backend.Model, **kwargs) → AbstractEntityT¶: Create new entity from given models by calling from_model with kwargs.

property hash_str¶

String used for hashing, with format <Class(ID->id)>.

Type: str

to_dict() → Dict[str, Any]¶: Convert the entity to a dictionary.

update_inner(**options: Any) → AbstractEntityT¶: Update self.options with options.

Song¶

class gd.Song(*, client: Optional[Client] = None, **options)[source]¶

Class that represents Geometry Dash/Newgrounds songs. This class is derived from AbstractEntity.

classmethod from_model(model: gd.model.SongModel, *, client: Optional[Client] = None, custom: bool = True) → Song [source]¶: Create new entity from given model, args and kwargs.

property name¶

A name of the song.

Type: str

property size¶

A float representing size of the song, in megabytes.

Type: float

property author¶

An author of the song.

Type: str

property link¶

A link to the song on Newgrounds, e.g. .../audio/listen/<id>.

Type: str

property download_link¶

A link to download the song, used in Song.download().

Type: str

is_custom() → bool [source]¶: bool: Indicates whether the song is custom or not.

get_author() → gd.song.Author[source]¶: Author: Author of the song.

async update(from_ng: bool = False) → None [source]¶

Update the song.

Parameters

from_ng (bool) – Whether to fetch song from Newgrounds.

Raises

MissingAccess – Failed to find the song.
HTTPStatusError – Server returned error status code.
HTTPError – Failed to process the request.

async get_artist_info() → gd.song.ArtistInfo[source]¶

Fetch artist info of self.

Acts like the following:

await client.get_artist_info(song.id)

Raises

MissingAccess – Failed to find artist info.
HTTPStatusError – Server returned error status code.
HTTPError – Failed to process the request.

Returns

Fetched info about an artist.

Return type

ArtistInfo

async download(file: Optional[Union[str, pathlib.Path, IO]] = None, with_bar: bool = False) → Optional[bytes][source]¶

Download a song from Newgrounds.

Parameters

file (Optional[Union[str, Path, IO]]) – File-like or Path-like object to write song to, instead of returning bytes.
with_bar (bool) – Whether to show a progress bar while downloading. Requires tqdm to be installed.

Raises

MissingAccess – Can not download the song because it is official or not found.
HTTPStatusError – Server returned error status code.
HTTPError – Failed to process the request.

Returns

A song as bytes, if file was not specified.

Return type

Optional[bytes]

attach_client(client: Optional[Client] = None) → AbstractEntityT¶

Attach client to self.

Parameters: client (Optional[gd.Client]) – Client to attach. If None or not given, will be detached.
Returns: This abstract entity.
Return type: AbstractEntity

property client¶

Client attached to this object. This checks if client is not present, and raises ClientException in that case.

Type: Client

property client_unchecked¶

Client attached to this object.

Type: Optional[Client]

detach_client() → AbstractEntityT¶

Detach client from self.

Same as calling:

self.attach_client(None)

Returns: This abstract entity.
Return type: AbstractEntity

classmethod from_dict(*data: Dict[str, Any], client: Optional[Client] = None, **kwargs) → AbstractEntityT¶: Create new entity from dictionaries in data, with client and kwargs.

classmethod from_dicts(*data: Dict[str, Any], client: Optional[Client] = None, **kwargs) → AbstractEntityT¶: Create new entity from dictionaries in data, with client and kwargs.

classmethod from_models(*models: gd.model_backend.Model, **kwargs) → AbstractEntityT¶: Create new entity from given models by calling from_model with kwargs.

property hash_str¶

String used for hashing, with format <Class(ID->id)>.

Type: str

property id¶

ID of the Entity.

Type: int

to_dict() → Dict[str, Any]¶: Convert the entity to a dictionary.

update_inner(**options: Any) → AbstractEntityT¶: Update self.options with options.