diff --git a/cmd/cmd.vcxproj b/cmd/cmd.vcxproj
index 24cf64a..b1e92ce 100644
--- a/cmd/cmd.vcxproj
+++ b/cmd/cmd.vcxproj
@@ -98,7 +98,7 @@
     <ClCompile>
       <WarningLevel>Level4</WarningLevel>
       <SDLCheck>true</SDLCheck>
-      <PreprocessorDefinitions>WIN32;_DEBUG;_CONSOLE;%(PreprocessorDefinitions)</PreprocessorDefinitions>
+      <PreprocessorDefinitions>DEBUG;WIN32;_DEBUG;_CONSOLE;%(PreprocessorDefinitions)</PreprocessorDefinitions>
       <ConformanceMode>true</ConformanceMode>
       <RuntimeLibrary>MultiThreadedDebug</RuntimeLibrary>
       <AdditionalIncludeDirectories>..\include\</AdditionalIncludeDirectories>
@@ -134,7 +134,7 @@
     <ClCompile>
       <WarningLevel>Level4</WarningLevel>
       <SDLCheck>true</SDLCheck>
-      <PreprocessorDefinitions>_DEBUG;_CONSOLE;%(PreprocessorDefinitions)</PreprocessorDefinitions>
+      <PreprocessorDefinitions>DEBUG;_DEBUG;_CONSOLE;%(PreprocessorDefinitions)</PreprocessorDefinitions>
       <ConformanceMode>true</ConformanceMode>
       <RuntimeLibrary>MultiThreadedDebug</RuntimeLibrary>
       <AdditionalIncludeDirectories>..\include\</AdditionalIncludeDirectories>
diff --git a/core/core.cpp b/core/core.cpp
index 921d0a6..714318c 100644
--- a/core/core.cpp
+++ b/core/core.cpp
@@ -1,5 +1,103 @@
 // core.cpp
-//   high level central operation of core functions
+//   High level central operation of core functions.
+//   Implementation of NSFCore members.
+//   Global utilities.
 
 #include "core.h"
 #include "enums_data.h"
+
+#include <cstdio> // std::fprintf, std::vsnprintf, stdout, stderr
+#include <cstdlib> // std::malloc, std::free, std::exit
+#include <cstring> // std:;memset, std::memcpy
+#include <cstdarg> // va_list, va_start
+
+namespace nsfp {
+
+void (*debug_print_callback)(const char* msg) = NULL;
+void (*fatal_callback)(const char* msg) = NULL;
+
+void* alloc(size_t size)
+{
+	void* a = std::malloc(size);
+	if (a == NULL) nsfp::fatal("Out of memory.");
+	NSFP_DEBUG("alloc(%z)=%p",size,a);
+	return a;
+}
+
+void free(void* ptr)
+{
+	NSFP_DEBUG("free(%p)",ptr);
+	std::free(ptr);
+}
+
+void debug(const char* msg)
+{
+	if (debug_print_callback) debug_print_callback(msg);
+	else std::fprintf(stdout,"%s\n",msg);
+}
+
+void debug_printf(const char* fmt,...)
+{
+#ifdef DEBUG
+	static char msg[1024];
+	va_list args;
+	va_start(args,fmt);
+	std::vsnprintf(msg,sizeof(msg),msg,args);
+#else
+	(void)fmt;
+#endif
+}
+
+void fatal(const char* msg)
+{
+	if (fatal_callback) fatal_callback(msg);
+	std::fprintf(stderr,"%s\n",msg);
+	std::exit(-1);
+}
+
+} // namespace nsfp
+
+NSFCore* NSFCore::create()
+{
+	NSFCore* core = (NSFCore*)nsfp::alloc(sizeof(NSFCore));
+	NSFP_DEBUG("create()=%p",core);
+	std::memset(core,0,sizeof(NSFCore));
+	core->set_default();
+	return core;
+}
+
+void NSFCore::destroy(NSFCore* core)
+{
+	NSFP_DEBUG("destroy(%p)",core);
+	core->release();
+	nsfp::free(core);
+}
+
+void NSFCore::finalize()
+{
+	// TODO make any allocations needed based on the settings
+}
+
+void NSFCore::release()
+{
+	// TODO release any allocations
+}
+
+void NSFCore::set_default()
+{
+	// TODO
+}
+
+bool NSFCore::set_ini(const char* ini)
+{
+	(void)ini;
+	// TODO
+	return false;
+}
+
+bool NSFCore::set_init(const NSFSetInit* init)
+{
+	(void)init;
+	// TODO
+	return false;
+}
diff --git a/core/core.h b/core/core.h
index 3beccb4..a71dec1 100644
--- a/core/core.h
+++ b/core/core.h
@@ -23,4 +23,46 @@ typedef uint16_t  uint16;
 typedef uint32_t  uint32;
 typedef uint64_t  uint64;
 
+#ifdef DEBUG
+#define NSFP_DEBUG(...) { nsfp::debug_printf(__VA_ARGS__); }
+#else
+#define NSFP_DEBUG(...) {}
+#endif
+
+// NSFCore structure, code members defined in core.cpp
+
+typedef struct NSFCore_
+{
+	sint32 set[NSFP_SET_COUNT]; // all integer settings (values for string settings will index set_str)
+	const char* set_str[NSFP_SETSTR_COUNT];
+	bool set_str_free[NSFP_SETSTR_COUNT]; // true if string setting
+
+	static NSFCore* create(); // After create: ->set_... then ->finalize.
+	static void destroy(NSFCore* core); // Calls ->release before freeing the core.
+	void finalize(); // finishes creation after create and initial settings
+	void release(); // called by destroy, releases all owned allocations
+
+	void set_default();
+	bool set_ini(const char* ini);
+	bool set_init(const NSFSetInit* init);
+
+} NSFCore;
+
+namespace nsfp {
+
+// core.cpp
+
+extern "C" {
+extern void (*debug_print_callback)(const char* msg);
+extern void (*fatal_callback)(const char* msg);
+}
+
+void* alloc(size_t size);
+void free(void* ptr);
+void debug_printf(const char* fmt,...); // only works if DEBUG defined
+void debug(const char* msg);
+void fatal(const char* msg);
+
+} // namespace nsfp
+
 #endif // __CORE_PCH__
diff --git a/core/core.vcxproj b/core/core.vcxproj
index cd4cc8c..042961e 100644
--- a/core/core.vcxproj
+++ b/core/core.vcxproj
@@ -98,7 +98,7 @@
     <ClCompile>
       <WarningLevel>Level4</WarningLevel>
       <SDLCheck>true</SDLCheck>
-      <PreprocessorDefinitions>WIN32;_DEBUG;_LIB;%(PreprocessorDefinitions)</PreprocessorDefinitions>
+      <PreprocessorDefinitions>DEBUG;WIN32;_DEBUG;_LIB;%(PreprocessorDefinitions)</PreprocessorDefinitions>
       <ConformanceMode>true</ConformanceMode>
       <PrecompiledHeader>Use</PrecompiledHeader>
       <PrecompiledHeaderFile>core.h</PrecompiledHeaderFile>
@@ -140,7 +140,7 @@
     <ClCompile>
       <WarningLevel>Level4</WarningLevel>
       <SDLCheck>true</SDLCheck>
-      <PreprocessorDefinitions>_DEBUG;_LIB;%(PreprocessorDefinitions)</PreprocessorDefinitions>
+      <PreprocessorDefinitions>DEBUG;_DEBUG;_LIB;%(PreprocessorDefinitions)</PreprocessorDefinitions>
       <ConformanceMode>true</ConformanceMode>
       <PrecompiledHeader>Use</PrecompiledHeader>
       <PrecompiledHeaderFile>core.h</PrecompiledHeaderFile>
diff --git a/core/nsfplaycore.cpp b/core/nsfplaycore.cpp
index e209099..0558ba7 100644
--- a/core/nsfplaycore.cpp
+++ b/core/nsfplaycore.cpp
@@ -2,3 +2,463 @@
 //   Contains the public interface.
 
 #include "core.h"
+
+NSFCore* nsfplay_create(const char* ini_data)
+{
+	NSFCore* core = NSFCore::create();
+	core->set_ini(ini_data);
+	core->finalize();
+	return core;
+}
+
+NSFCore* nsfplay_create_init(const NSFSetInit* init)
+{
+	NSFCore* core = NSFCore::create();
+	core->set_init(init);
+	core->finalize();
+	return core;
+}
+
+void nsfplay_destroy(NSFCore* core)
+{
+	NSFCore::destroy(core);
+}
+
+// TODO: everything below this line
+
+const char* nsfplay_last_error(NSFCore* core)
+{
+	(void)core;
+	return NULL;
+}
+
+void nsfplay_set_debug_print(void (*debug_print_callback_)(const char* msg))
+{
+	nsfp::debug_print_callback = debug_print_callback_;
+}
+
+void nsfplay_set_fatal(void (*fatal_callback_)(const char* msg))
+{
+	nsfp::fatal_callback = fatal_callback_;
+}
+
+void nsfplay_set_default(NSFCore* core)
+{
+	(void)core;
+}
+
+bool nsfplay_set_ini(NSFCore* core, const char* ini_data)
+{
+	(void)core;
+	(void)ini_data;
+	return false;
+}
+
+bool nsfplay_set_init(NSFCore* core, const NSFSetInit* init)
+{
+	(void)core;
+	(void)init;
+	return false;
+}
+
+const char* nsfplay_ini_line(const NSFCore* core, int32_t index)
+{
+	(void)core;
+	(void)index;
+	return NULL;
+}
+
+bool nsfplay_set_int(NSFCore* core, int32_t index, int32_t value)
+{
+	(void)core;
+	(void)index;
+	(void)value;
+	return false;
+}
+
+bool nsfplay_set_str(NSFCore* core, int32_t index, const char* value)
+{
+	(void)core;
+	(void)index;
+	(void)value;
+	return false;
+}
+
+int32_t nsfplay_get_int(const NSFCore* core, int32_t index)
+{
+	(void)core;
+	(void)index;
+	return 0;
+}
+
+const char* nsfplay_get_str(const NSFCore* core, int32_t index)
+{
+	(void)core;
+	(void)index;
+	return NULL;
+}
+
+bool nsfplay_set_key_int(NSFCore* core, const char* key, int32_t value)
+{
+	(void)core;
+	(void)key;
+	(void)value;
+	return false;
+}
+
+bool nsfplay_set_key_str(NSFCore* core, const char* key, const char* value)
+{
+	(void)core;
+	(void)key;
+	(void)value;
+	return false;
+}
+
+int32_t nsfplay_get_key_int(const NSFCore* core, const char* key)
+{
+	(void)core;
+	(void)key;
+	return 0;
+}
+
+const char* nsfplay_get_key_str(const NSFCore* core, const char* key)
+{
+	(void)core;
+	(void)key;
+	return NULL;
+}
+
+NSFSetInfo nsfplay_set_info(int32_t index)
+{
+	(void)index;
+	return {};
+}
+
+NSFSetGroupInfo nsfplay_set_group_info(int32_t group)
+{
+	(void)group;
+	return {};
+}
+
+int32_t nsfplay_set_key_index(const char* key)
+{
+	(void)key;
+	return 0;
+}
+
+int32_t nsfplay_set_group_index(const char* key)
+{
+	(void)key;
+	return 0;
+}
+
+bool nsfplay_load(NSFCore* core, const void* nsf_data, uint32_t nsf_size)
+{
+	(void)core;
+	(void)nsf_data;
+	(void)nsf_size;
+	return false;
+}
+
+bool nsfplay_assume(NSFCore* core, const void* nsf_data, uint32_t nsf_size)
+{
+	(void)core;
+	(void)nsf_data;
+	(void)nsf_size;
+	return false;
+}
+
+uint32_t nsfplay_song_count(const NSFCore* core)
+{
+	(void)core;
+	return 0;
+}
+
+bool nsfplay_song(NSFCore* core, uint8_t song)
+{
+	(void)core;
+	(void)song;
+	return false;
+}
+
+void nsfplay_song_play(NSFCore* core)
+{
+	(void)core;
+}
+
+void nsfplay_seek(NSFCore* core, uint64_t samples)
+{
+	(void)core;
+	(void)samples;
+}
+
+uint64_t nsfplay_samples_played(const NSFCore* core)
+{
+	(void)core;
+	return 0;
+}
+
+uint32_t nsfplay_render(NSFCore* core, uint32_t samples, int16_t* stereo_output)
+{
+	(void)core;
+	(void)samples;
+	(void)stereo_output;
+	return 0;
+}
+
+uint8_t nsfplay_emu_peek(const NSFCore* core, uint16_t address)
+{
+	(void)core;
+	(void)address;
+	return 0;
+}
+
+uint8_t nsfplay_emu_read(NSFCore* core, uint16_t address)
+{
+	(void)core;
+	(void)address;
+	return 0;
+}
+
+void nsfplay_emu_poke(NSFCore* core, uint16_t address, uint8_t value)
+{
+	(void)core;
+	(void)address;
+	(void)value;
+}
+
+void nsfplay_emu_reg_set(NSFCore* core, char reg, uint16_t value)
+{
+	(void)core;
+	(void)reg;
+	(void)value;
+}
+
+uint16_t nsfplay_emu_reg_get(const NSFCore* core, char reg)
+{
+	(void)core;
+	(void)reg;
+	return 0;
+}
+
+void nsfplay_emu_run(NSFCore* core, uint32_t cycles)
+{
+	(void)core;
+	(void)cycles;
+}
+
+uint32_t nsfplay_emu_samples_pending(const NSFCore* core)
+{
+	(void)core;
+	return 0;
+}
+
+void nsfplay_emu_cancel_pending(NSFCore* core)
+{
+	(void)core;
+}
+
+uint64_t nsfplay_emu_cycles(const NSFCore* core)
+{
+	(void)core;
+	return 0;
+}
+
+uint32_t nsfplay_emu_cycles_to_next_sample(const NSFCore* core)
+{
+	(void)core;
+	return 0;
+}
+
+NSFPropInfo nsfplay_prop_info(const NSFCore* core, int32_t prop)
+{
+	(void)core;
+	(void)prop;
+	return {};
+}
+
+NSFPropInfo nsfplay_prop_song_info(const NSFCore* core, int32_t song, int32_t prop)
+{
+	(void)core;
+	(void)song;
+	(void)prop;
+	return {};
+}
+
+int32_t nsfplay_prop_int(const NSFCore* core, int32_t prop)
+{
+	(void)core;
+	(void)prop;
+	return 0;
+}
+
+int64_t nsfplay_prop_long(const NSFCore* core, int32_t prop)
+{
+	(void)core;
+	(void)prop;
+	return 0;
+}
+
+const char* nsfplay_prop_str(const NSFCore* core, int32_t prop)
+{
+	(void)core;
+	(void)prop;
+	return NULL;
+}
+
+int32_t nsfplay_prop_lines(const NSFCore* core, int32_t prop)
+{
+	(void)core;
+	(void)prop;
+	return 0;
+}
+
+const char* nsfplay_prop_line(const NSFCore* core)
+{
+	(void)core;
+	return NULL;
+}
+
+const void* nsfplay_prop_blob(const NSFCore* core, uint32_t* blob_size)
+{
+	(void)core;
+	(void)blob_size;
+	return NULL;
+}
+
+int32_t nsfplay_prop_song_type(const NSFCore* core, int32_t song, int32_t prop)
+{
+	(void)core;
+	(void)song;
+	(void)prop;
+	return 0;
+}
+
+int32_t nsfplay_prop_song_int(const NSFCore* core, int32_t song, int32_t prop)
+{
+	(void)core;
+	(void)song;
+	(void)prop;
+	return 0;
+}
+
+int64_t nsfplay_prop_song_long(const NSFCore* core, int32_t song, int32_t prop)
+{
+	(void)core;
+	(void)song;
+	(void)prop;
+	return 0;
+}
+
+const char* nsfplay_prop_song_str(const NSFCore* core, int32_t song, int32_t prop)
+{
+	(void)core;
+	(void)song;
+	(void)prop;
+	return NULL;
+}
+
+int32_t nsfplay_prop_song_lines(const NSFCore* core, int32_t song, int32_t prop)
+{
+	(void)core;
+	(void)song;
+	(void)prop;
+	return 0;
+}
+
+const void* nsfplay_prop_song_blob(const NSFCore* core, int32_t song, uint32_t* blob_size)
+{
+	(void)core;
+	(void)song;
+	(void)blob_size;
+	return NULL;
+}
+
+const void* nsfplay_chunk(const NSFCore* core, const char* fourcc, uint32_t* chunk_size)
+{
+	(void)core;
+	(void)fourcc;
+	(void)chunk_size;
+	return NULL;
+}
+
+NSFChannelUnit nsfplay_channel_unit(const NSFCore* core, int32_t unit)
+{
+	(void)core;
+	(void)unit;
+	return {};
+}
+
+NSFChannelInfo nsfplay_channel_info(int32_t global_channel)
+{
+	(void)global_channel;
+	return {};
+}
+
+int32_t nsfplay_channel_count(const NSFCore* core)
+{
+	(void)core;
+	return 0;
+}
+
+NSFChannelState nsfplay_channel_state(const NSFCore* core, int32_t active_channel)
+{
+	(void)core;
+	(void)active_channel;
+	return {};
+}
+
+uint32_t nsfplay_channel_state_ex(const NSFCore* core, int32_t active_channel, void* data, uint32_t data_size)
+{
+	(void)core;
+	(void)active_channel;
+	(void)data;
+	(void)data_size;
+	return 0;
+}
+
+uint64_t nsfplay_time_to_samples(const NSFCore* core, int32_t hours, int32_t minutes, int32_t seconds, int32_t milliseconds)
+{
+	(void)core;
+	(void)hours;
+	(void)minutes;
+	(void)seconds;
+	(void)milliseconds;
+	return 0;
+}
+
+uint64_t nsfplay_time_to_cycles(const NSFCore* core, int32_t hours, int32_t minutes, int32_t seconds, int32_t milliseconds)
+{
+	(void)core;
+	(void)hours;
+	(void)minutes;
+	(void)seconds;
+	(void)milliseconds;
+	return 0;
+}
+
+void nsfplay_samples_to_time(const NSFCore* core, uint64_t samples, int32_t* hours, int32_t* minutes, int32_t* seconds, int32_t* milliseconds)
+{
+	(void)core;
+	(void)samples;
+	(void)hours;
+	(void)minutes;
+	(void)seconds;
+	(void)milliseconds;
+}
+
+void nsfplay_cycles_to_time(const NSFCore* core, uint64_t cycles, int32_t* hours, int32_t* minutes, int32_t* seconds, int32_t* milliseconds)
+{
+	(void)core;
+	(void)cycles;
+	(void)hours;
+	(void)minutes;
+	(void)seconds;
+	(void)milliseconds;
+}
+
+const char* nsfplay_local_text(int32_t key)
+{
+	(void)key;
+	return NULL;
+}
diff --git a/enums/nsfplayenums.py b/enums/nsfplayenums.py
index fee6fec..e03eef8 100644
--- a/enums/nsfplayenums.py
+++ b/enums/nsfplayenums.py
@@ -726,6 +726,7 @@ def generate_enums(file_enum,file_data,do_write):
     gen_line("\tconst char* default_str;",1)
     gen_line("} NSFSetData;",1)
     gen_line("const NSFSetData NSFPD_SET[NSFP_SET_COUNT] = {",1)
+    setstr_count = 0
     for si in range(len(defs_set)):
         gi = defs_set[si][0]
         group_key = defs_setgroup[gi][0]
@@ -734,6 +735,8 @@ def generate_enums(file_enum,file_data,do_write):
         default_str = "NULL"
         if defs_set[si][6]:
             default_str = "\""+defs_set[si][2]+"\""
+            default_int = setstr_count # default_int for string settings reused internally as as a lookup index to a string array
+            setstr_count += 1
         else:
             default_int = defs_set[si][2]
             if (default_int < defs_set[si][3]) or (default_int > defs_set[si][4]):
@@ -765,6 +768,7 @@ def generate_enums(file_enum,file_data,do_write):
                     descs[j] = descs[0]
             table_locale[i].append(gen_text(names[i]))
             table_locale[i].append(gen_text(descs[i]))
+    gen_enum("NSFP_SETSTR_COUNT",setstr_count)
     gen_break(0)
     gen_line("};",1)
     gen_break(1)
diff --git a/gui/gui.vcxproj b/gui/gui.vcxproj
index 2832592..f53c76b 100644
--- a/gui/gui.vcxproj
+++ b/gui/gui.vcxproj
@@ -98,7 +98,7 @@
     <ClCompile>
       <WarningLevel>Level4</WarningLevel>
       <SDLCheck>true</SDLCheck>
-      <PreprocessorDefinitions>__WXMSW__;WIN32;_DEBUG;_LIB;%(PreprocessorDefinitions)</PreprocessorDefinitions>
+      <PreprocessorDefinitions>__WXMSW__;DEBUG;WIN32;_DEBUG;_LIB;%(PreprocessorDefinitions)</PreprocessorDefinitions>
       <ConformanceMode>true</ConformanceMode>
       <PrecompiledHeader>NotUsing</PrecompiledHeader>
       <PrecompiledHeaderFile>pch.h</PrecompiledHeaderFile>
@@ -138,7 +138,7 @@
     <ClCompile>
       <WarningLevel>Level4</WarningLevel>
       <SDLCheck>true</SDLCheck>
-      <PreprocessorDefinitions>__WXMSW__;_DEBUG;_LIB;%(PreprocessorDefinitions)</PreprocessorDefinitions>
+      <PreprocessorDefinitions>__WXMSW__;DEBUG;_DEBUG;_LIB;%(PreprocessorDefinitions)</PreprocessorDefinitions>
       <ConformanceMode>true</ConformanceMode>
       <PrecompiledHeader>NotUsing</PrecompiledHeader>
       <PrecompiledHeaderFile>pch.h</PrecompiledHeaderFile>
@@ -176,6 +176,7 @@
   </ItemDefinitionGroup>
   <ItemGroup>
     <ClCompile Include="gui.cpp" />
+    <ClCompile Include="nsfplaygui.cpp" />
   </ItemGroup>
   <ItemGroup>
     <ClInclude Include="..\include\nsfplaycore.h" />
diff --git a/gui/gui.vcxproj.filters b/gui/gui.vcxproj.filters
index e434290..9d56733 100644
--- a/gui/gui.vcxproj.filters
+++ b/gui/gui.vcxproj.filters
@@ -29,5 +29,8 @@
     <ClCompile Include="gui.cpp">
       <Filter>Source Files</Filter>
     </ClCompile>
+    <ClCompile Include="nsfplaygui.cpp">
+      <Filter>Source Files</Filter>
+    </ClCompile>
   </ItemGroup>
 </Project>
\ No newline at end of file
diff --git a/gui/nsfplaygui.cpp b/gui/nsfplaygui.cpp
new file mode 100644
index 0000000..803ede5
--- /dev/null
+++ b/gui/nsfplaygui.cpp
@@ -0,0 +1,33 @@
+// nsfplaygui.cpp
+//   Contains the public interface.
+
+#include <nsfplaygui.h>
+
+void* nsfplay_gui_about(void * parent)
+{
+	(void)parent;
+	// TODO
+	return NULL;
+}
+
+void* nsfplay_gui_core(NSFCore* core, void* parent, void (*core_lock)(), void (*core_unlock)())
+{
+	(void)core;
+	(void)parent;
+	(void)core_lock;
+	(void)core_unlock;
+	// TODO
+	return NULL;
+}
+
+// opens a settings window for the core
+void* nsfplay_gui_settings(NSFCore* core, void* parent, bool modal, void (*core_lock)(), void (*core_unlock)())
+{
+	(void)core;
+	(void)parent;
+	(void)modal;
+	(void)core_lock;
+	(void)core_unlock;
+	// TODO
+	return NULL;
+}
diff --git a/include/nsfplaycore.h b/include/nsfplaycore.h
index 52d8b92..e6dbd03 100644
--- a/include/nsfplaycore.h
+++ b/include/nsfplaycore.h
@@ -10,8 +10,8 @@
 // - The song index begins at 0 for the interface, but when presented to the user a +1 should be used,
 //   so that the first song in the NSF is song 1.
 
-#include <stdint.h>
-#include <stddef.h>
+#include <stdint.h> // explicit size integer types
+#include <stddef.h> // NULL
 
 // auto-generated enumerations for settings and properties
 #include "nsfplayenums.h"
@@ -20,7 +20,8 @@ extern "C"
 {
 
 // hidden implementation
-struct NSFCore;
+struct NSFCore_;
+typedef struct NSFCore_ NSFCore;
 
 
 typedef struct
@@ -30,6 +31,7 @@ typedef struct
 	const char* val_str; // NULL if not string
 } NSFSetInit;
 
+
 // create or destroy an core instance
 // - ini_data is a null terminated string, containing ini file settings
 // - a NULL ini_data will use the default settings
@@ -38,14 +40,41 @@ NSFCore* nsfplay_create(const char* ini_data);
 NSFCore* nsfplay_create_init(const NSFSetInit* init);
 void nsfplay_destroy(NSFCore* core);
 
-// reset all settings to default values
-void nsfplay_set_default(NSFCore* core);
-
 // returns a localized string describing the last error
 //  - NULL if there has been no logged error since the last call to nsfplay_test_error
 //  - once returned, the error state will be cleared, and subsequent calls will return NULL until another error is caught
 const char* nsfplay_last_error(NSFCore* core);
 
+// for debug builds, sets a custom debug output function for diagnostics
+// - default will print to stdout.
+// - debug msg will not end with newline.
+void nsfplay_set_debug_print(void (*debug_print_callback)(const char* msg));
+
+// set a callback to handle a fatal error
+// - May be called if out of memory or some other irrecoverable error.
+// - Allows you to report the error message in some other way before exiting, luck willing.
+// - If no callback is provided, or if it returns, it will print msg to stderr,
+//   then std::exit(-1) to close the application.
+// - fatal msg will not end with newline.
+void nsfplay_set_fatal(void (*fatal_callback)(const char* msg));
+
+
+// reset all settings to default values
+void nsfplay_set_default(NSFCore* core);
+// apply ini file or init array
+bool nsfplay_set_ini(NSFCore* core, const char* ini_data);
+bool nsfplay_set_init(NSFCore* core, const NSFSetInit* init);
+
+// ini file
+// - returns false if any lines could not be parsed
+// - settings are separated by line endings, any combination of cr and/or lf is accepted
+// - blank lines are ignored, anything after # will be ignored until the next line
+// read a current setting as an ini line
+// - does not include newline
+// - iterate from 0 to NSFP_SET_COUNT-1 to generate a complete ini file
+const char* nsfplay_ini_line(const NSFCore* core, int32_t index);
+
+
 // settings by index
 // - use the provided NSFP_SET_x enumerations, because index values are subject to change
 // - set returns false if index is out of bounds, or the wrong value type was used
@@ -62,16 +91,6 @@ bool nsfplay_set_key_str(NSFCore* core, const char* key, const char* value);
 int32_t nsfplay_get_key_int(const NSFCore* core, const char* key);
 const char* nsfplay_get_key_str(const NSFCore* core, const char* key);
 
-// ini file
-// - returns false if any lines could not be parsed
-// - settings are separated by line endings, any combination of cr and/or lf is accepted
-// - blank lines are ignored, anything after # will be ignored until the next line
-bool nsfplay_ini(NSFCore* core, const char* ini_data);
-// read a current setting as an ini line
-// - does not include newline
-// - iterate from 0 to NSFP_SET_COUNT-1 to generate a complete ini file
-const char* nsfplay_ini_line(const NSFCore* core, int32_t index);
-
 // information about settings, useful for UI display
 
 typedef struct
@@ -112,10 +131,6 @@ bool nsfplay_load(NSFCore* core, const void* nsf_data, uint32_t nsf_size);
 bool nsfplay_assume(NSFCore* core, const void* nsf_data, uint32_t nsf_size);
 
 
-// convenience function for time conversion
-uint64_t nsfplay_time_to_samples(const NSFCore* core, int32_t hours, int32_t minutes, int32_t seconds, int32_t milliseconds);
-void nsfplay_samples_to_time(const NSFCore* core, uint64_t samples, int32_t* hours, int32_t* minutes, int32_t* seconds, int32_t* milliseconds);
-
 // song control
 uint32_t nsfplay_song_count(const NSFCore* core); // number of songs in loaded NSF
 bool nsfplay_song(NSFCore* core, uint8_t song); // set song, false if song out of bounds, automatically calls song_play
@@ -223,7 +238,14 @@ NSFChannelState nsfplay_channel_state(const NSFCore* core, int32_t active_channe
 uint32_t nsfplay_channel_state_ex(const NSFCore* core, int32_t active_channel, void* data, uint32_t data_size);
 
 
+// convenience functions for time conversion
+uint64_t nsfplay_time_to_samples(const NSFCore* core, int32_t hours, int32_t minutes, int32_t seconds, int32_t milliseconds);
+uint64_t nsfplay_time_to_cycles(const NSFCore* core, int32_t hours, int32_t minutes, int32_t seconds, int32_t milliseconds);
+void nsfplay_samples_to_time(const NSFCore* core, uint64_t samples, int32_t* hours, int32_t* minutes, int32_t* seconds, int32_t* milliseconds);
+void nsfplay_cycles_to_time(const NSFCore* core, uint64_t cycles, int32_t* hours, int32_t* minutes, int32_t* seconds, int32_t* milliseconds);
+
 // other text strings adapted for the current locale, see: NSFP_TEXT_key
+// - the returned string pointer is static and has permanent lifetime
 const char* nsfplay_local_text(int32_t key);
 
 
diff --git a/include/nsfplayenums.h b/include/nsfplayenums.h
index dbe20fc..31bae91 100644
--- a/include/nsfplayenums.h
+++ b/include/nsfplayenums.h
@@ -1,6 +1,6 @@
 #pragma once
 // generated by nsfplayenums.py
-// 2024-04-21 04:21:35
+// 2024-04-21 15:52:36
 
 #define NSFP_LIST_COUNT                                     2
 #define NSFP_LIST_ENABLE                                    0
@@ -43,6 +43,7 @@
 #define NSFP_SET_APU1_DPCM_ON                              17
 #define NSFP_SET_APU1_DPCM_VOL                             18
 #define NSFP_SET_APU1_DPCM_PAN                             19
+#define NSFP_SETSTR_COUNT                                   1
 
 #define NSFP_PROP_COUNT                                     5
 #define NSFP_PROP_SONGCOUNT                                 0
diff --git a/makefile.common b/makefile.common
index cd57bb2..977e723 100644
--- a/makefile.common
+++ b/makefile.common
@@ -23,6 +23,10 @@ MKDIR ?= mkdir -p
 
 OPTIMIZE ?= -O3
 
+# set DEBUG=1 to define DEBUG for C++ compilation
+
+DEBUG ?= 0
+
 # wxWidgets
 
 WXL_DEBUG ?= 0
@@ -35,11 +39,17 @@ else
 	WXL_DEBUG_SUFFIX ?= d
 endif
 
+ifeq ($(DEBUG),1)
+	CXXFLAGS_DEBUG ?= -DDEBUG
+else
+	CXXFLAGS_DEBUG ?=
+endif
+
 # platform settings
 
 ifeq ($(OS),Windows_NT)
 	# Windows (MSYS2, gcc)
-	CXXFLAGS_EXTRA ?= -municode
+	CXXFLAGS_EXTRA ?= -municode $(CXXFLAGS_DEBUG)
 	LDFLAGS_EXTRA ?= -static -static-libgcc -static-libstdc++ -Wl,--fatal-warnings
 	LDFLAGS_CMD ?= -mconsole
 	LDFLAGS_GUI ?=
@@ -77,7 +87,7 @@ ifeq ($(OS),Windows_NT)
 	#   comctl32.lib, rpcrt4.lib, ws2_32.lib, wininet.lib, winmm.lib
 else ifeq ($(shell uname),Darwin)
 	# MacOS (clang)
-	CXXFLAGS_EXTRA ?= -Wno-c++11-extension
+	CXXFLAGS_EXTRA ?= -Wno-c++11-extension $(CXXFLAGS_DEBUG)
 	LDFLAGS_EXTRA ?=
 	LDFLAGS_CMD ?=
 	LDFLAGS_GUI ?=
@@ -94,7 +104,7 @@ else ifeq ($(shell uname),Darwin)
 	WXL_CONFIG ?= $(WXL_DIR)/$(WXL_CMAKEDIR)/wx-config
 else
 	# Linux / Other (gcc)
-	CXXFLAGS_EXTRA ?=
+	CXXFLAGS_EXTRA ?= $(CXXFLAGS_DEBUG)
 	LDFLAGS_EXTRA ?= -Wl,--fatal-warnings
 	LDFLAGS_CMD ?=
 	LDFLAGS_GUI ?=
diff --git a/nsfplay/nsfplay.vcxproj b/nsfplay/nsfplay.vcxproj
index b9bb7ad..048a519 100644
--- a/nsfplay/nsfplay.vcxproj
+++ b/nsfplay/nsfplay.vcxproj
@@ -99,7 +99,7 @@
     <ClCompile>
       <WarningLevel>Level4</WarningLevel>
       <SDLCheck>true</SDLCheck>
-      <PreprocessorDefinitions>__WXMSW__;WIN32;_DEBUG;_WINDOWS;%(PreprocessorDefinitions)</PreprocessorDefinitions>
+      <PreprocessorDefinitions>__WXMSW__;DEBUG;WIN32;_DEBUG;_WINDOWS;%(PreprocessorDefinitions)</PreprocessorDefinitions>
       <ConformanceMode>true</ConformanceMode>
       <RuntimeLibrary>MultiThreadedDebug</RuntimeLibrary>
       <AdditionalIncludeDirectories>..\include\;..\wxlib\include\;..\wxlib\lib\vc_lib\mswud\</AdditionalIncludeDirectories>
@@ -137,7 +137,7 @@
     <ClCompile>
       <WarningLevel>Level4</WarningLevel>
       <SDLCheck>true</SDLCheck>
-      <PreprocessorDefinitions>__WXMSW__;_DEBUG;_WINDOWS;%(PreprocessorDefinitions)</PreprocessorDefinitions>
+      <PreprocessorDefinitions>__WXMSW__;DEBUG;_DEBUG;_WINDOWS;%(PreprocessorDefinitions)</PreprocessorDefinitions>
       <ConformanceMode>true</ConformanceMode>
       <RuntimeLibrary>MultiThreadedDebug</RuntimeLibrary>
       <AdditionalIncludeDirectories>..\include\;..\wxlib\include\;..\wxlib\lib\vc_x64_lib\mswud\</AdditionalIncludeDirectories>
diff --git a/winamp/winamp.vcxproj b/winamp/winamp.vcxproj
index dfba158..10419a8 100644
--- a/winamp/winamp.vcxproj
+++ b/winamp/winamp.vcxproj
@@ -59,7 +59,7 @@
     <ClCompile>
       <WarningLevel>Level4</WarningLevel>
       <SDLCheck>true</SDLCheck>
-      <PreprocessorDefinitions>__WXMSW__;WIN32;_DEBUG;WINAMP_EXPORTS;_WINDOWS;_USRDLL;%(PreprocessorDefinitions)</PreprocessorDefinitions>
+      <PreprocessorDefinitions>__WXMSW__;DEBUG;WIN32;_DEBUG;WINAMP_EXPORTS;_WINDOWS;_USRDLL;%(PreprocessorDefinitions)</PreprocessorDefinitions>
       <ConformanceMode>true</ConformanceMode>
       <PrecompiledHeader>NotUsing</PrecompiledHeader>
       <PrecompiledHeaderFile>pch.h</PrecompiledHeaderFile>