Products            Buy            Support Forum            Professional            About            Codec Central
  uPlayer: Scripting & Command Line
uPlayer is a small efficient player, designed to be the most efficient (in terms of memory footprint and resources used) audio player ever created. Features advanced abilities such as gapless playback, ReplayGain, multi-zones & collections and floating point abilities of DSP effects. Most functionality of uPlayer can be controlled either through scripting from any COM aware programs (c++, .NET, Visual Basic Scripting), or from the command line (CLI).

License:  uPlayer can be used by individuals non-commercially without restriction (subject to it not being distributed). If uPlayer used commercially, or is supplied as part of system:  Email your intentions.

  uPlayer CLI  

uPlayer is called directly through illustrate\dBpoweramp\uPlayer.exe

-zone="device:settings:shownname" if omitted, default is 'waveout:-1:(default)'
-collection="collection_name" if omitted, default is '(global)'
-skipnext skip to next track
-skipprev skip back to begin, or previous track (if < 5 seconds into current)
-stop stops playback (pass zone and collection if not default)
-close close player (zone dependent)
-play="filename" play file
-play (no filename) continue after a stop
-enqueue="filename" queue file  (does not start playing)
-penqueue="filename" priority queue file  (does not start playing)
-volume="x" set volume 1..100
-skippc="x" skip to x %  (0 to 100)


"c:\program files\illustrate\dbpoweramp\uplayer.exe" // start player
"c:\program files\illustrate\dbpoweramp\uplayer.exe" -enqueue="c:\somefile.mp3" // queue a file (and playback will auto begin)
"c:\program files\illustrate\dbpoweramp\uplayer.exe" -enqueue="c:\anotherfile.mp3" // queue another file

or more advanced:

"c:\program files\illustrate\dbpoweramp\uplayer.exe" -collection="bob" -zone="waveout:1:z1{;}waveout:2:z2" // start player, outputting 'bob' collection to zone 1 & zone 2
"c:\program files\illustrate\dbpoweramp\uplayer.exe" -collection="spoon" -zone="waveout:3:z3" // start player, outputting 'spoon' collection to zone 3
"c:\program files\illustrate\dbpoweramp\uplayer.exe" -collection="bob" -enqueue="c:\somefile.mp3" // queue a file for bob
"c:\program files\illustrate\dbpoweramp\uplayer.exe" -collection="spoon" -enqueue="c:\somefile1.mp3" // queue a file for bob
"c:\program files\illustrate\dbpoweramp\uplayer.exe" -collection="spoon" -pause // pause spoon playback

Noting certain calls to uPlayer.exe will not return if the player is being started, where as others, such as -enqueue return instantly.

  uPlayer Scripting  

uPlayer contains a built in COM object called uPlayer. See examples provided at the end of this section on how to access this object in various languages.

Set Collection & Zone:  .SetCollectionZone ([in] BSTR Collection, [in] BSTR Zone) 

Collection:    Name of collection, multiple players can be instigated by specifying different collections.
Zone:    Name of the output Zone, output to 2 zones by seperating with {;}, ie. waveout:1:z1{;}waveout:2:z2

If no collection or Zones are specified (ie SetCollectionZone is never called then (global) & waveout:-1:(default) are used for collection and zone. Normally .SetCollection is called once before any of the below functions.

Enque a file: .Enqueue ([in] BSTR File, [in] long Priority )

File:    Audio filename (including path).
:    0=normal  1=priority enqueued

Skip to Next Track: .SkipNext ( )

Skip to Previous Track: .SkipPrevious ( )
(or beginning of current track if > 5 seconds into playback)

Skip to % Position in Current Track: .SkipToPC ( [in] long PC )

PC:    Position 0 to 100 

Set / Get Volume: .Volume     [retval] long

Volume can be 1 to 100, ie

uPlayer.Volume = 75
CurrentVolume = uPlayer.Volume

Play a file: .Play ([in] BSTR File )

File:    Audio filename (including path)

NB: File can be empty ("") to remove a Stop

Mute: .Mute ( )

UnMute: .UnMute ( )

Test if Muted: .IsMuted      [retval] long

Returns 0 if not muted, 1 if muted

Pause: .Pause ( )

UnPause: .UnPause ( )

Test if Paused: .IsPaused      [retval] long

Returns 0 if not paused, 1 if paused

Close uPlayer: .Close ( )

NB is Zone & Collection dependent

Test if Player is Loaded: .IsLoaded      [retval] long

Returns 0 if not loaded, 1 if loaded

Load uPlayer: .Load ( )

Playback would start instantly if something was queued (unless player is in a forced stopped state)

Stop uPlayer: .Stop ( )

Puts player in stopped state (sound devices are freed), call Play("") or Play(filename)  to start again

Test if Player is Playing: .IsStopped      [retval] long

Returns 0 playing track, 1 not playing track

The following Properties relate to the current playing track, .PlayingPropsChanged can be polled to determine if something has changed (might be filename, or position):

.FilePlaying      [retval] BSTR             filename of track playing
.PlayingLengthMS         length of the file in mili-seconds
.PlayingPositionPC       current position %
.PlayingPositionMS       current position mili-seconds
.PlayingBitRate              in bps ie 128000

 Scripting Code Examples  

Example scripting code for:

C++     additional include files:  uPlayer_i.c   uPlayer.h

.NET c#

.NET Visual Basic

Windows Scripting Host VB Script

 uPlayer Storage and Queue  


(collection)-previous.bin Previous Files Played (capped at 500 files)
(collection)-pqueue.bin Priority enqueued
(collection)-queue.bin Enqueued
** saved as unicode [MAX_PATH * 2] per file record

default-dsps.bin DSPs used by default unless a collection dsp file is present
(collection)-dsps.bin DSPs used by a collection
** -dsps.bin saved as unicode   ShowName\r\nSettings\r\nShowName1\r\nSettings1

Any dBpoweramp 'Live' DSP effect can be used.