Core_Engine

The Core Engine page documents the current public workflow exposed by PDJE. The engine facade owns the root database handle, constructs audioPlayer instances, exposes the editor subsystem, and forwards the core data line used by other modules.

Older versions of this manual kept most editor operation details here. The current docs split responsibilities differently:

Core_Engine covers facade entrypoints and playback control.
Editor_Workflows covers project setup, mutation, history, render/push, and preview playback.
Class editorObject remains the exact member lookup page.

Public Entry Points

enum PLAY_MODE

the play mode you can use this to initialize the player(music handler) to use fx control in real time, do not use Full pre render.

Values:

enumerator FULL_PRE_RENDER

enumerator HYBRID_RENDER

enumerator FULL_MANUAL_RENDER

class PDJE

the main Interface of this Engine PDJE gets music data and track data from database. from that datas, you can activate music player and you can get a music player handler. with this player handler, you can control music’s mixing in real time.

to-use

make PDJE object
call SearchTrack
call InitPlayer
use player. this is handler.

PLAY_MODE determines how InitPlayer() configures the player:

FULL_PRE_RENDER builds a pre-rendered playback path.
HYBRID_RENDER builds a pre-rendered path and enables manual music / FX control panels.
FULL_MANUAL_RENDER constructs the manual player path without loading a track into the player constructor.

Typical Playback Flow

Construct PDJE with the root database path.
Search for music or tracks through SearchMusic() and SearchTrack().
Create a player with InitPlayer().
Call Activate() / Deactivate() on the returned audioPlayer.
Pull the core data line when you need playback state from another module.

Selected facade methods:

MUS_VEC PDJE::SearchMusic(const UNSANITIZED &Title, const UNSANITIZED &composer, const double bpm = -1)

searches musics and metadatas from database. if you don’t need to filter, send “” to the values

Parameters:

Title – the title of the music
composer – the composer of the music
bpm – the bpm of the music. send under zero to skip filter

Returns:

MUS_VEC

TRACK_VEC PDJE::SearchTrack(const UNSANITIZED &Title)

searches track the track contains the note data, mix data and included music lists.

Parameters:: Title – the title of the track. send “” to skip filter
Returns:: TRACK_VEC the array of the track_data. find what you want

bool PDJE::InitPlayer(PLAY_MODE mode, trackdata &td, const unsigned int FrameBufferSize)

this inits the music handler. the music handler called a “player” it initializes the player

Parameters:

mode – the play modes. you can choose “FULL_PRE_RENDER”, “HYBRID_RENDER”, “FULL_MANUAL_RENDER”
td – the track data. you can get this from SearchTrack()
FrameBufferSize – the buffersize. in this project, it uses 48000 samplerate. if you use 48 as a value, in theory, it calls mixing function 1000 times per second.

Returns:

true no error

Returns:

false error

std::shared_ptr<audioPlayer> PDJE::GetPlayerObject()

music handler getter api for binded codes. this function gives you a music handler. you can access player directly in cpp, but not in binded languages. so this function exists.

Returns:: audioPlayer* the player object.check nullptr before use.

PDJE_CORE_DATA_LINE PDJE::PullOutDataLine()

PDJE engine("database/path");

auto tracks = engine.SearchTrack("example-track");
if (tracks.empty()) {
    return;
}

if (!engine.InitPlayer(PLAY_MODE::HYBRID_RENDER, tracks.front(), 480)) {
    return;
}

auto player = engine.GetPlayerObject();
if (!player) {
    return;
}

(void)player->Activate();
auto line = engine.PullOutDataLine();
(void)player->Deactivate();
engine.ResetPlayer();

PDJE::PullOutDataLine() returns an empty PDJE_CORE_DATA_LINE until a player exists. Reacquire the line after recreating or resetting the player because the owned storage can move.

Wrapper Bindings

The older manual pages also described the wrapper-facing entry points. That material still matters in the current tree:

C# and Python bindings are generated only when PDJE_SWIG_BUILD=ON.
The SWIG output mirrors the core/editor facade with names such as PDJE, audioPlayer, editorObject, and PLAY_MODE.
The Godot wrapper uses PDJE_Wrapper and PlayerWrapper instead of the raw C++ class names.
The current SWIG output keeps the legacy Pannel spelling for manual-control methods such as GetFXControlPannel() and GetMusicControlPannel().

Quick start by binding:

C++

PDJE engine("database/path");
auto tracks = engine.SearchTrack("example-track");
if (tracks.empty()) {
    return;
}

if (!engine.InitPlayer(PLAY_MODE::HYBRID_RENDER, tracks.front(), 480)) {
    return;
}

auto player = engine.GetPlayerObject();
if (!player) {
    return;
}

(void)player->Activate();
(void)player->Deactivate();
engine.ResetPlayer();

C#

PDJE engine = new PDJE("database/path");
TRACK_VEC tracks = engine.SearchTrack("example-track");
if (tracks.Count == 0) {
    return;
}

if (!engine.InitPlayer(PLAY_MODE.HYBRID_RENDER, tracks[0], 480)) {
    return;
}

audioPlayer player = engine.GetPlayerObject();
if (player == null) {
    return;
}

player.Activate();
player.Deactivate();
engine.ResetPlayer();

PYTHON

import pdje_POLYGLOT as pypdje

engine = pypdje.PDJE("database/path")
tracks = engine.SearchTrack("example-track")
if len(tracks) == 0:
    raise RuntimeError("track not found")

if not engine.InitPlayer(pypdje.HYBRID_RENDER, tracks[0], 480):
    raise RuntimeError("player init failed")

player = engine.GetPlayerObject()
if player is None:
    raise RuntimeError("player handle unavailable")

player.Activate()
player.Deactivate()
engine.ResetPlayer()

GDSCRIPT

var engine:PDJE_Wrapper = PDJE_Wrapper.new()
engine.InitEngine("res://database/path")

var tracks = engine.SearchTrack("example-track")
if tracks.is_empty():
    return

if not engine.InitPlayer(PDJE_Wrapper.HYBRID_RENDER, tracks[0], 480):
    return

var player:PlayerWrapper = engine.GetPlayer()
if player == null:
    return

player.Activate()
player.Deactivate()
engine.ResetPlayer()

Player Control

audioPlayer is the runtime playback object returned by InitPlayer().

bool audioPlayer::Activate()

Plays music.

the handler status. check when something wrong. do not change this manually.

bool audioPlayer::Deactivate(): Stops music.

unsigned long long audioPlayer::GetConsumedFrames()

gets consumed frames. with this, you can get how many frames are consumed and music’s playback time. to get playback time, divide the returned value with 48000. The result is Seconds.

Returns:: consumed frames

FXControlPanel *audioPlayer::GetFXControlPanel(const UNSANITIZED &title = "__PDJE__MAIN__")

fx controller getter this returns the fx controller. with this, you can control the fx in realtime manually.

Parameters:: title – the music to control. “__PDJE__MAIN__” means the prerendered music.
Returns:: FXControlPanel* but the “title” doesn’t exists, it returns nullptr.

MusicControlPanel *audioPlayer::GetMusicControlPanel()

music controller getter this returns the music controller. with this, you can load music, stop music in realtime manually.

Returns:: MusicControlPanel* if something wrong, it returns nullptr.

Manual control panels are available only when the player was created with manual features enabled, which in the current code path means HYBRID_RENDER or FULL_MANUAL_RENDER.

Note

Native C++ uses GetFXControlPanel() / GetMusicControlPanel(). The current SWIG wrapper output still exposes the same panel handles with the legacy method names GetFXControlPannel() / GetMusicControlPannel().

FX Control

enum FXList

the usable fx list

Values:

enumerator COMPRESSOR

enumerator DISTORTION

enumerator ECHO

enumerator EQ

enumerator FILTER

enumerator FLANGER

enumerator OCSFILTER

enumerator PANNER

enumerator PHASER

enumerator ROBOT

enumerator ROLL

enumerator TRANCE

enumerator VOL

void FXControlPanel::FX_ON_OFF(FXList fx, bool onoff)

activate/deactivate FX

Parameters:

fx – the fx type
onoff – activate / deactivate

ARGSETTER FXControlPanel::GetArgSetter(FXList fx)

Get the Arg Setter object.

Parameters:: fx – the fx type
Returns:: ARGSETTER the FX arg handler

bool FXControlPanel::checkSomethingOn()

check any FX is activated

Returns:: true , something is activated
Returns:: false , nothing activated.

auto fx = player->GetFXControlPanel();
if (fx) {
    fx->FX_ON_OFF(FXList::FILTER, true);
    auto args = fx->GetArgSetter(FXList::FILTER);
    args["HLswitch"](0.0);
    args["Filterfreq"](1200.0);
}

Music Control

class MusicControlPanel: Music handler for manual mode.

bool MusicControlPanel::LoadMusic(litedb &ROOTDB, const musdata &Mus)

loads music to the deck. doesn’t play music

Parameters:: Mus – Searched music
Returns:: int, miniaudio Error code.

bool MusicControlPanel::SetMusic(const UNSANITIZED &title, const bool onOff)

turn on, off the music

Parameters:

title – the music title
onOff – True is on, False is off

Returns:

true

Returns:

false

bool MusicControlPanel::CueMusic(const UNSANITIZED &title, const unsigned long long newPos)

Change playback position of the music.

Parameters:

title – the music title
newPos – the new playback position of the music

Returns:

true

Returns:

false

bool MusicControlPanel::UnloadMusic(const UNSANITIZED &title)

unload music from deck. used to prevent memory leaks.

Parameters:: title – the target music title
Returns:: true
Returns:: false

LOADED_LIST MusicControlPanel::GetLoadedMusicList()

get music list on the deck

Returns:: LOADED_LIST

bool MusicControlPanel::ChangeBpm(const UNSANITIZED &title, const double targetBpm, const double originBpm)

changes music’s bpm

Parameters:

title – the title of the music
targetBpm – the target bpm of the music
originBpm – the origin bpm of the music

Returns:

true

Returns:

false

auto music_panel = player->GetMusicControlPanel();
if (music_panel) {
    auto found = engine.SearchMusic("song-title", "composer-name", -1.0);
    if (!found.empty()) {
        (void)music_panel->LoadMusic(*engine.DBROOT, found.front());
        (void)music_panel->SetMusic(found.front().title, true);
    }
}

Editor Entry Points

The editor is a major authoring subsystem behind the same PDJE facade. This page covers the entry sequence only. For the operational workflow around project-local editing, typed mutations, render/push behavior, and history APIs, read Editor_Workflows.

If you were using the older “Editor Step-1/2/3/4” manual, the material moved there is now grouped by operation family:

project setup and open/reopen flow
line mutation and typed readback
history and time-travel operations
render and push-to-root-db flow
preview playback through demoPlayInit()

bool PDJE::InitEditor(const DONT_SANITIZE &auth_name, const DONT_SANITIZE &auth_email, const DONT_SANITIZE &projectRoot)

Initializes the editor.

Parameters:

auth_name – The author’s name for Git commits.
auth_email – The author’s email for Git commits.
projectRoot – The root directory of the editor project.

Returns:

true if the editor was initialized successfully, false otherwise.

inline std::shared_ptr<editorObject> PDJE::GetEditorObject()

editor handler getter api for binded codes. this function gives you a editor handler.

Returns:: editorObject* the editor object. check nullptr before use.

inline void PDJE::CloseEditor(): Close the Editor object.

bool editorObject::Open(const fs::path &projectPath, const DONT_SANITIZE &auth_name, const DONT_SANITIZE &auth_email)

Opens an existing editor project. if PDJE called InitEditor, you don’t need to call this again.

Parameters:: projectPath – The path to the project.
Returns:: true if the project was opened successfully, false otherwise.

bool editorObject::ConfigNewMusic(const UNSANITIZED &NewMusicName, const UNSANITIZED &composer, const fs::path &musicPath, const DONT_SANITIZE &firstBeat = "0")

Configures a new music entry.

Parameters:

NewMusicName – The unsanitized name of the new music.
composer – The unsanitized composer of the new music.
musicPath – The path to the music file.
firstBeat – The first Beat of the music (defaults to “0”).

Returns:

true if the configuration was successful, false otherwise.

if (!engine.InitEditor("Author Name", "author@example.com", "project-root")) {
    return;
}

auto editor = engine.GetEditorObject();
if (!editor) {
    return;
}

(void)editor->ConfigNewMusic("Song", "Composer", "audio/song.wav", "0");
engine.CloseEditor();

From this point on, use Editor_Workflows for the authoring flow. Use Class editorObject when you need exact overloads for AddLine(), Undo(), GetLogWithJSONGraph(), render(), pushToRootDB(), or demoPlayInit().