PyAIMP documentation

Welcome! This documentation is about PyAIMP, a Python AIMP remote API wrapper with some extras.

pyversion pypiv pypil

PyAIMP comes as a simple Python module that covers the main features of the AIMP remote API features with the help of pywin32 (the only dependency).

Prerequisites

  • Python 3.5+
  • AIMP

Installation

The usual way:

$ pip install pyaimp

The McGyver way, after cloning/downloading this repo:

$ python setup.py install

Usage

Create a pyaimp.Client instance and you are ready to use any of its public methods.

Example displaying the current playback state:

import pyaimp

try:
    client = pyaimp.Client()

    state = client.get_playback_state()

    if state == pyaimp.PlayBackState.Stopped:
        print('AIMP actually doesn\'t play anything')
    elif state == pyaimp.PlayBackState.Paused:
        print('AIMP is taking a break')
    elif state == pyaimp.PlayBackState.Playing:
        print('Rock \'n Roll baby')
except RuntimeError as re: # AIMP instance not found
    print(re)
except Exception as e:
    print(e)

Continue reading to know about what you can do.

Note

  • AIMP events aren’t supported.
  • The album image retrieving isn’t supported, too. I tried, but it’s way too hard/tricky to implement.

API docs

class pyaimp.PlayBackState

Enumeration (extending enum.Enum) of all possible AIMP playback states.

May be used in conjonction with pyaimp.Client.get_playback_state() result.

Paused = 1

The current track playback is currently suspended.

Playing = 2

A track is being played.

Stopped = 0

There’s currently no track being played.

class pyaimp.Client

Main class of the pyaimp module which is the wrapper around the AIMP remote API.

When a new instance of this class is created, it will search for the current AIMP window handle using pyaimp.Client.detect_aimp(). If none are found, a RuntimeError exception will be raised.

Note

Consider all methods in this class to be blocking and non-thread safe.

Raises:RuntimeError – The AIMP window cannot be found.
add_dirs_to_playlist(dir)

CLI /DIR command: Add folder(s) to the playlist.

Whether playing of added the files starts depends on the player settings.

Parameters:dir (str) – Path to a directory
Return type:None
add_files_dialog()

Display the “Add Files” dialog window.

Return type:None
add_files_to_playlist(file)

CLI /FILE command: Add file(s) to the playlist.

Whether playing of added the files starts depends on the player settings.

Parameters:file (str) – Path to a file
Return type:None
add_folders_dialog()

Display the “Add Folders” dialog window.

Return type:None
add_playlists_dialog()

Display the “Add Playlists” dialog window.

Return type:None
add_to_active_playlist(obj)

CLI /INSERT command: Add objects to the active playlist.

Whether playing of added the files starts depends on the player settings.

Parameters:obj (str) – Path to a playlist, folder or file
Return type:None
add_to_active_playlist_custom(obj)

CLI /QUEUE command: Add objects to the active playlist and put them in custom playback queue.

Parameters:obj (str) – Path to a playlist, folder or file
Return type:None
add_to_bookmarks(obj)

CLI /BOOKMARK command: Add files and/or folders to your bookmarks.

Parameters:obj (str) – Path to a folder or file
Return type:None
add_to_playlist_and_play(obj)

CLI /ADD_PLAY command: Add objects to a playlist and start playing.

Parameters:obj (str) – Path to a playlist, folder or file
Return type:None
add_url_dialog()

Display the “Add URLs” dialog window.

Return type:None
detect_aimp()

Detect the AIMP window handler and the full path to its executable, which are required in order to be able to remote control AIMP.

This method is automatically called for you when creating a new instance of this class.

This method may be useful for you when AIMP is closed, then restarted for any reason. You’ll need to call it to retrieve the newly created AIMP window handler or you won’t be able to use the same instance anymore.

There isn’t anything returned because it defines internal attributes.

Raises:RuntimeError – The AIMP window cannot be found.
Return type:None
get_current_track_duration()

Return the current track duration, in milliseconds.

Return type:int
get_current_track_info()

Return a dictionary of information about the current active track.

Dictionary keys are:

  • bit_rate (int): Audio bit rate
  • channels (int): Number of audio channels
  • duration (int): Duration of the track, in milliseconds. 0 if unknown or none (i.e a stream)
  • file_size (int): Size of the file, in bytes. 0 if unknown or none (i.e a stream)
  • file_mark (int): Unknown
  • track_number (int): Track number (as stored in the audio tags). 0 if unknown
  • sample_rate (int): Audio sample rate
  • album (str): Album name or an empty string if none
  • artist (str): Artist name or an empty string if unknown
  • year (int): Track year or an empty string if unknown
  • filename (str): Path to the track or URL to the stream
  • genre (str): Track genre or an empty string if unknown
  • title (str): Track title or an empty string if unknown
Return type:dict
get_playback_state()

Return the current playback state. The returned value is equal to one of the pyaimp.PlayBackState enumeration.

Return type:pyaimp.PlayBackState.Stopped or pyaimp.PlayBackState.Paused or pyaimp.PlayBackState.Playing
get_player_position()

Return the current player position as the number of elapsed milliseconds since the beginning of the track.

Return type:int
get_version()

Return the AIMP version as a tuple containing the major version and the build number, e.g ('4.12', 1878).

Return type:tuple
get_volume()

Return the current volume, in percents.

Return type:int
is_muted()

Return the muted state of the player.

Return type:bool
is_recording()

Return the radio recording state of the player.

Return type:bool
is_shuffled()

Return the shuffle state of the player.

Return type:bool
is_track_repeated()

Return the repeat state of the player.

Return type:bool
is_visualization_fullscreen()

Return whether the visualization is fullscreen or not.

Return type:bool
next()

Start playing the next track in the playlist.

Return type:None
next_visualization()

Start the next visualization.

Return type:None
open_files_dialog()

Display the “Open Files” dialog window.

Return type:None
open_folders_dialog()

Display the “Open Folders” dialog window.

Return type:None
open_playlists_dialog()

Display the “Open Playlists” dialog window.

Return type:None
pause()

Different behaviors may be encountered when using this method:

  • If the player is playing, this will pause playback.
  • If the player is paused, this will resume playback.
Return type:None
play()

Different behaviors may be encountered when using this method:

  • If the player is stopped, this will start playback.
  • If the player is paused, this will resume playback.
  • If the player is playing, this will start playback from beginning.
Return type:None
play_pause()

Different behaviors may be encountered when using this method:

  • If the player is stopped, this will start playback.
  • If the player is paused, this will resume playback.
  • If the player is playing, this will start pauses playback.
Return type:None
prev()

Start playing the previous track in the playlist.

Return type:None
prev_visualization()

Start the previous visualization.

Return type:None
quit()

Shutdown and exit AIMP.

You’ll obviously not be able to do anything after using this method until AIMP is opened again and pyaimp.Client.detect_aimp() is manually called.

Return type:None
set_muted(muted)

Set the muted state of the player.

Parameters:muted (bool) – Whether the player should be muted or not
Return type:None
set_player_position(position)

Set the current player position.

Parameters:position (int) – Number of elapsed milliseconds since the beginning of the track
Return type:None
set_recording(recording)

Set the radio recording state of the player.

Parameters:recording (bool) – Whether the radio recording should be active or not
Return type:None
set_shuffled(shuffled)

Set the shuffle state of the player.

Parameters:shuffled (bool) – Whether the tracks should be shuffled or not
Return type:None
set_track_repeated(repeat)

Set the repeat state of the player.

Parameters:repeat (bool) – Whether the track should be repeated or not
Return type:None
set_visualization_fullscreen(visualization_fullscreen)

Set the visualization to be fullscreen or not.

Parameters:visualization_fullscreen (bool) – Whether the visualization should be fullscreen or not
Return type:None
set_volume(volume)

Set the current volume.

Parameters:volume (int) – The new volume, in percent
Return type:None
start_visualization()

Start the visualization.

Return type:None
stop()

Stop the playback.

Return type:None
stop_visualization()

Stop the visualization.

Return type:None