Merge pull request #25 from hendriks73/support_emojis

Support emojis. Added CLAUDE.md.

Author: hendriks73

CLAUDE.md

@@ -0,0 +1,121 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+---
+
+## Task Execution Guidelines
+
+Follow these practices for all non-trivial work in this repository.
+
+### Plan before coding
+
+Before writing any code, think through the approach. For any task beyond a trivial fix:
+1. Draft a plan — identify the files to change, the interfaces to add/modify, and the test cases needed.
+2. Review the plan against the constraints in this file.
+3. Only start editing once the plan is coherent. A bad plan caught early is far cheaper than a bad implementation caught late.
+
+### Write tests first
+
+When adding new functionality, write the failing test before writing the implementation. A failing test creates an immediate, objective feedback loop. This dramatically improves reliability — run the test after every meaningful change to stay oriented.
+
+### Break work into small increments
+
+Prefer many small, verifiable steps over one large change. Each increment should:
+- Leave the codebase in a working state (tests pass, linter clean).
+- Be independently reviewable.
+
+If a task feels too large to hold in one session, decompose it further.
+
+---
+
+## Project Overview
+
+FFSampledSP is a Java/JNI library that implements `javax.sound.sampled` service provider interfaces (SPIs) backed by FFmpeg. It decodes audio files/streams to signed linear PCM. Licensed under LGPL 2.1.
+
+## Build Commands
+
+The build requires Maven 3.6+, a JDK, and Doxygen. Native compilation requires platform-specific toolchains. **A platform profile must be activated** — native modules are not built by default.
+
+### macOS (native for current platform)
+```bash
+# Build and test for aarch64 (Apple Silicon)
+mvn --activate-profiles ffsampledsp-aarch64-macos install
+
+# Build and test for x86_64
+mvn --activate-profiles ffsampledsp-x86_64-macos install
+```
+
+### Linux
+```bash
+mvn --activate-profiles ffsampledsp-x86_64-linux install
+# For aarch64 cross-compile (requires aarch64-linux-gnu-gcc, tests are skipped):
+mvn --activate-profiles ffsampledsp-aarch64-linux install
+```
+
+### Windows (requires MSYS2 with MinGW toolchain)
+```bash
+mvn --activate-profiles ffsampledsp-x86_64-win install   # 64-bit
+mvn --activate-profiles ffsampledsp-i386-win install     # 32-bit (tests skipped)
+```
+
+### Java-only (no native compilation)
+```bash
+mvn install  # builds ffsampledsp-java and ffsampledsp-complete only
+```
+
+### Run tests
+Tests live in `ffsampledsp-complete/src/test/java/`. They require the native library to be built first (via a platform profile).
+
+```bash
+# Run all tests (after native build)
+mvn --activate-profiles ffsampledsp-aarch64-macos test
+
+# Run a single test class
+mvn --activate-profiles ffsampledsp-aarch64-macos test \
+  -pl ffsampledsp-complete \
+  -Dtest=TestFFAudioFileReader
+```
+
+### Debug builds
+Pass `-Dcflags=-DDEBUG` to enable C-level debug output to stdout.
+
+## Architecture
+
+### Module Structure
+
+- **`ffsampledsp-java/`** — Pure Java SPI implementations. The authoritative Java source; compiled standalone but also copied into `ffsampledsp-complete` at build time.
+- **`ffsampledsp-{arch}-{host}/`** — Per-platform native modules (`x86_64-macos`, `aarch64-macos`, `x86_64-linux`, `aarch64-linux`, `x86_64-win`, `i386-win`). Each packages a `.dylib`/`.so`/`.dll`. The C sources live only in `ffsampledsp-x86_64-macos/src/main/c/` — all other platform modules symlink or reference the same sources.
+- **`ffsampledsp-complete/`** — The distribution artifact. Copies Java sources from `ffsampledsp-java` and embeds the native library from whichever platform profile is active. This is the jar users depend on.
+
+### Java/JNI Layer
+
+The Java classes in `com.tagtraum.ffsampledsp` implement the `javax.sound.sampled.spi` interfaces:
+
+- **`FFAudioFileReader`** — implements `AudioFileReader`. Opens URLs/files/streams via FFmpeg. Caches results (LRU, 20 entries). Has a `getAudioFileFormats()` extension returning multiple formats for multi-stream files (e.g. Stems). Calls into native via two `native` methods: `getAudioFileFormatsFromURL` and `getAudioFileFormatsFromBuffer`.
+- **`FFFormatConversionProvider`** — implements `AudioFormatConversionProvider`. Transcodes compressed streams to PCM.
+- **`FFNativePeerInputStream`** — abstract base for native-backed `InputStream`s. Holds a `long pointer` to the native C struct and a direct `ByteBuffer` (`nativeBuffer`) that the C side fills.
+  - **`FFURLInputStream`** — decodes from a URL/file path.
+  - **`FFStreamInputStream`** — decodes from a Java `InputStream` (reads into a buffer, probes format, then decodes).
+  - **`FFCodecInputStream`** — handles format conversion (resampling/channel mapping) using `libswresample`.
+- **`FFAudioInputStream`** — wraps an `FFNativePeerInputStream`, implements seeking via `FFGlobalLock`.
+- **`FFGlobalLock`** — a single `ReentrantLock` (`LOCK`) used to serialize FFmpeg calls that are not thread-safe (`avcodec_open2`, etc.).
+- **`FFNativeLibraryLoader`** — extracts the embedded native library to `java.io.tmpdir` and loads it. Naming convention: `ffsampledsp-{arch}-{host}.{ext}` (e.g. `ffsampledsp-aarch64-macos.dylib`).
+
+Java language/compiler is specified in the main pom.xml file.
+
+### C Native Layer (`ffsampledsp-x86_64-macos/src/main/c/`)
+
+- **`FFUtils.c` / `FFUtils.h`** — shared helpers: JNI field/method ID caching, buffer management, FFmpeg context lifecycle, DRM detection (`CODEC_TAG_DRMS`). Minimum probe score of 5 prevents misdetecting files that other `javax.sound.sampled` providers should handle.
+- **`FFAudioFileReader.c`** — native implementation of the two `FFAudioFileReader` native methods. Probes format, fills Java `FFAudioFileFormat` / `FFAudioFormat` objects.
+- **`FFURLInputStream.c`** — opens an `AVFormatContext` from a URL, decodes packets into the Java `nativeBuffer`.
+- **`FFStreamInputStream.c`** — uses FFmpeg's custom I/O (`AVIOContext` with read callbacks) to pull data from a Java `InputStream`.
+- **`FFCodecInputStream.c`** — wraps `libswresample` for PCM conversion.
+
+### Key Design Points
+
+- The native library is embedded inside `ffsampledsp-complete.jar` and extracted to a temp file on first load. The extracted filename includes the version to allow side-by-side installs; SNAPSHOT builds are always re-extracted.
+- All calls touching FFmpeg's non-thread-safe API are wrapped in `FFGlobalLock.LOCK`.
+- Windows URLs require a special format for libav: `file:C:/path/file` (not `file:///C:/path/file`). UNC paths use `file://server/path`. This conversion happens in `FFAudioFileReader.urlToString()`.
+- The `fileToURL` method explicitly decodes then re-encodes file URIs to preserve `+` characters in paths (a known edge case).
+- JNI headers are auto-generated by `javac -h` during the `compile` phase into `target/native/include/`, then consumed by the platform-specific native module.

NOTES.md

@@ -1,5 +1,6 @@
 - 0.9.54
-  - Updated Maven project report skin (fixing the *Fork Me*-banner).  
+  - Updated Maven project report skin (fixing the *Fork Me*-banner).
+  - Support emojis and %20 in paths.
 
 
 - 0.9.53

ffsampledsp-complete/src/test/java/com/tagtraum/ffsampledsp/TestFFAudioFileReader.java

@@ -26,6 +26,7 @@
 
 import javax.sound.sampled.AudioFileFormat;
 import javax.sound.sampled.AudioFormat;
+import javax.sound.sampled.AudioInputStream;
 import javax.sound.sampled.UnsupportedAudioFileException;
 import java.io.*;
 import java.net.MalformedURLException;
@@ -326,6 +327,110 @@ public void testGetAudioFileFormatURL() throws IOException, UnsupportedAudioFile
         }
     }
 
+    @Test
+    public void testGetAudioFileFormatURLWithEmojis() throws IOException, UnsupportedAudioFileException {
+        // first copy the file from resources to actual location in temp
+        final String filename = "test.ogg";
+        final File file = File.createTempFile("testGetAudioFileFormatURLWithEmojis🔥", filename);
+        extractFile(filename, file);
+        try {
+            final AudioFileFormat fileFormat = new FFAudioFileReader().getAudioFileFormat(file.toURI().toURL());
+            System.out.println(fileFormat);
+
+            assertEquals("ogg", fileFormat.getType().getExtension());
+            assertEquals(file.length(), fileFormat.getByteLength());
+            assertEquals(NOT_SPECIFIED, fileFormat.getFrameLength());
+
+            final AudioFormat format = fileFormat.getFormat();
+            assertEquals(NOT_SPECIFIED, format.getFrameSize());
+            assertEquals(2, format.getChannels());
+            final Long duration = (Long)fileFormat.getProperty("duration");
+            assertNotNull(duration);
+            assertEquals(3030204, (long)duration);
+            assertEquals((float)NOT_SPECIFIED, format.getFrameRate(), 0.001f);
+            final Integer bitrate = (Integer)format.getProperty("bitrate");
+            assertNotNull("Bitrate missing", bitrate);
+            assertEquals(112000, (int) bitrate);
+        } finally {
+            file.delete();
+        }
+    }
+
+    @Test
+    public void testGetAudioFileFormatFileWithEmojis() throws IOException, UnsupportedAudioFileException {
+        // Tests that getAudioFileFormat(File) handles emoji in the file name.
+        // This path goes through fileToURL(), which must keep emoji percent-encoded
+        // so JNI's GetStringUTFChars does not produce CESU-8 (Modified UTF-8) bytes
+        // that differ from the standard UTF-8 bytes used by the file system.
+        final String filename = "test.ogg";
+        final File file = File.createTempFile("testGetAudioFileFormatFileWithEmojis🔥", filename);
+        extractFile(filename, file);
+        try {
+            final AudioFileFormat fileFormat = new FFAudioFileReader().getAudioFileFormat(file);
+            System.out.println(fileFormat);
+            assertEquals("ogg", fileFormat.getType().getExtension());
+            assertEquals(2, fileFormat.getFormat().getChannels());
+        } finally {
+            file.delete();
+        }
+    }
+
+    @Test
+    public void testGetAudioInputStreamFileWithEmojis() throws IOException, UnsupportedAudioFileException {
+        // Tests that getAudioInputStream(File) can open and read a file whose
+        // name contains emoji. Exercises the FFURLInputStream.open() JNI call.
+        final String filename = "test.ogg";
+        final File file = File.createTempFile("testGetAudioInputStreamFileWithEmojis🎵", filename);
+        extractFile(filename, file);
+        try {
+            final AudioInputStream stream = new FFAudioFileReader().getAudioInputStream(file);
+            try {
+                final byte[] buf = new byte[1024];
+                assertTrue("Expected to read audio bytes from emoji-named file", stream.read(buf) > 0);
+            } finally {
+                stream.close();
+            }
+        } finally {
+            file.delete();
+        }
+    }
+
+    @Test
+    public void testFileWithEmojiToURL() throws MalformedURLException {
+        // fileToURL() must produce a valid file: URL for paths containing emoji.
+        // The native code uses ff_jstring_to_utf8() (String.getBytes("UTF-8")) rather than
+        // GetStringUTFChars so that supplementary characters like emoji are correctly encoded
+        // as standard UTF-8 bytes — matching the bytes stored on disk — regardless of whether
+        // the URL string contains the emoji as a raw character or percent-encoded.
+        Assume.assumeTrue(File.separator.equals("/"));
+        final File file = new File("/someDir/test🔥/name.ogg");
+        final URL url = FFAudioFileReader.fileToURL(file);
+        assertTrue("URL must use file: protocol: " + url, url.toString().startsWith("file:"));
+        // The emoji must be represented in the URL in some form (raw or percent-encoded).
+        assertTrue("URL must contain emoji path component: " + url,
+                url.toString().contains("test🔥") || url.toString().contains("%F0%9F%94%A5") || url.toString().contains("%f0%9f%94%a5"));
+        // The path decoded from the URL must end with the original file name.
+        assertTrue("Decoded path must contain original file name: " + url,
+                url.getFile().contains("test") && url.getFile().contains("name.ogg"));
+    }
+
+    @Test
+    public void testGetAudioFileFormatURLWithSpaces() throws IOException, UnsupportedAudioFileException {
+        // Tests that getAudioFileFormat(URL) handles spaces in the file path.
+        // file.toURI().toURL() encodes spaces as %20; urlToString() must decode
+        // them before passing to FFmpeg, which does not percent-decode file: paths.
+        final String filename = "test.ogg";
+        final File file = File.createTempFile("test with spaces", filename);
+        extractFile(filename, file);
+        try {
+            final AudioFileFormat fileFormat = new FFAudioFileReader().getAudioFileFormat(file.toURI().toURL());
+            assertEquals("ogg", fileFormat.getType().getExtension());
+            assertEquals(2, fileFormat.getFormat().getChannels());
+        } finally {
+            file.delete();
+        }
+    }
+
     @Test
     public void testGetAudioFileFormatInputStream() throws IOException, UnsupportedAudioFileException {
         // first copy the file from resources to actual location in temp

ffsampledsp-java/src/main/java/com/tagtraum/ffsampledsp/FFAudioFileReader.java

@@ -139,10 +139,21 @@ static URL fileToURL(final File file) throws MalformedURLException {
     /**
      * Make sure that file URLs on Windows follow the super special libav style, e.g. "file:C:/path/file.ext"
      * or "file://UNCServerName/path/file.ext".
+     * For file: URLs on all platforms, percent-encoded sequences (e.g. %20 for space) are decoded
+     * because FFmpeg's file: protocol handler passes the path directly to the OS without decoding.
      */
     static String urlToString(final URL url) {
         if (url == null) return null;
-        final String s = url.toString();
+        String s = url.toString();
+        if (s.startsWith("file:")) {
+            // FFmpeg's file: protocol handler does not percent-decode paths, so decode here.
+            // Protect '+' first so URLDecoder does not convert it to a space.
+            try {
+                s = URLDecoder.decode(s.replace("+", "%2B"), "UTF-8");
+            } catch (UnsupportedEncodingException e) {
+                // UTF-8 is always available; cannot happen
+            }
+        }
         if (WINDOWS && s.matches("file\\:/[^\\/].*")) {
             return s.replace("file:/", "file:");
         }

ffsampledsp-x86_64-macos/src/main/c/FFAudioFileReader.c

@@ -396,7 +396,16 @@ static int create_ffaudiofileformats(JNIEnv *env, AVFormatContext *format_contex
 
     init_ids(env);
 
-    const char *input_url = (*env)->GetStringUTFChars(env, url, NULL);
+    // Use ff_jstring_to_utf8 instead of GetStringUTFChars: the JNI function returns
+    // Modified UTF-8 (CESU-8), which encodes supplementary characters (U+10000+, e.g.
+    // emoji) as 6 bytes rather than the standard UTF-8 4-byte sequence.  File systems
+    // use standard UTF-8, so avformat_open_input would fail to find such files.
+    char *input_url = ff_jstring_to_utf8(env, url);
+    if (!input_url) {
+        throwIOExceptionIfError(env, AVERROR(ENOMEM), "Failed to convert URL to UTF-8");
+        goto bail;
+    }
+
     res = ff_open_format_context(env, &format_context, input_url);
     if (res) {
         goto bail;
@@ -411,7 +420,7 @@ static int create_ffaudiofileformats(JNIEnv *env, AVFormatContext *format_contex
     if (format_context) {
         avformat_close_input(&format_context);
     }
-    (*env)->ReleaseStringUTFChars(env, url, input_url);
+    free(input_url);
 
     return array;
 }

ffsampledsp-x86_64-macos/src/main/c/FFURLInputStream.c

@@ -58,11 +58,14 @@ JNIEXPORT jlong JNICALL Java_com_tagtraum_ffsampledsp_FFURLInputStream_open(JNIE
     int res = 0;
     FFAudioIO *aio = NULL;
 
-    // copy URL to local char*
-    const char *input_url = (*env)->GetStringUTFChars(env, url, NULL);
+    // Use ff_jstring_to_utf8 instead of GetStringUTFChars: the JNI function returns
+    // Modified UTF-8 (CESU-8), which encodes supplementary characters (U+10000+, e.g.
+    // emoji) as 6 bytes rather than the standard UTF-8 4-byte sequence.  File systems
+    // use standard UTF-8, so avformat_open_input would fail to find such files.
+    char *input_url = ff_jstring_to_utf8(env, url);
     if (!input_url) {
         res = AVERROR(ENOMEM);
-        throwIOExceptionIfError(env, res, "Failed to get url");
+        throwIOExceptionIfError(env, res, "Failed to convert URL to UTF-8");
         goto bail;
     }
 
@@ -97,8 +100,8 @@ JNIEXPORT jlong JNICALL Java_com_tagtraum_ffsampledsp_FFURLInputStream_open(JNIE
 bail:
 
     if (res) ff_audioio_free(aio);
-    (*env)->ReleaseStringUTFChars(env, url, input_url);
-    
+    free(input_url);
+
     return (jlong)(intptr_t)aio;
 }
 

ffsampledsp-x86_64-macos/src/main/c/FFUtils.c

@@ -1197,4 +1197,40 @@ JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM *vm, void *reserved) {
     avformat_network_init();
     //avcodec_register_all();
     return JNI_VERSION_1_6;
+}
+
+char *ff_jstring_to_utf8(JNIEnv *env, jstring java_string) {
+    jclass string_class = NULL;
+    jmethodID get_bytes_mid = NULL;
+    jstring utf8_charset = NULL;
+    jbyteArray bytes = NULL;
+    jsize len = 0;
+    char *result = NULL;
+
+    if (!java_string) return NULL;
+
+    string_class = (*env)->GetObjectClass(env, java_string);
+    if (!string_class) goto bail;
+
+    get_bytes_mid = (*env)->GetMethodID(env, string_class, "getBytes", "(Ljava/lang/String;)[B");
+    if (!get_bytes_mid) goto bail;
+
+    utf8_charset = (*env)->NewStringUTF(env, "UTF-8");
+    if (!utf8_charset) goto bail;
+
+    bytes = (jbyteArray)(*env)->CallObjectMethod(env, java_string, get_bytes_mid, utf8_charset);
+    if (!bytes) goto bail;
+
+    len = (*env)->GetArrayLength(env, bytes);
+    result = (char *)malloc(len + 1);
+    if (!result) goto bail;
+
+    (*env)->GetByteArrayRegion(env, bytes, 0, len, (jbyte *)result);
+    result[len] = '\0';
+
+bail:
+    if (utf8_charset) (*env)->DeleteLocalRef(env, utf8_charset);
+    if (bytes)        (*env)->DeleteLocalRef(env, bytes);
+
+    return result;
 }

ffsampledsp-x86_64-macos/src/main/c/FFUtils.h

@@ -116,4 +116,23 @@ int ff_init_encoder(JNIEnv*, FFAudioIO*, AVCodec*);
 
 int ff_big_endian(enum AVCodecID);
 
+/**
+ * Converts a Java string to a standard UTF-8 C string.
+ *
+ * JNI's GetStringUTFChars returns Modified UTF-8 (CESU-8), which encodes supplementary
+ * characters (U+10000 and above, e.g. emoji) as two 3-byte sequences (6 bytes total)
+ * instead of the single 4-byte sequence used by standard UTF-8. File systems on macOS
+ * and Linux use standard UTF-8 for file names, so paths containing emoji passed through
+ * GetStringUTFChars will not match the file on disk.
+ *
+ * This function calls java.lang.String.getBytes("UTF-8") via JNI, which always returns
+ * standard UTF-8 bytes regardless of the characters involved.
+ *
+ * The caller must free() the returned buffer when no longer needed.
+ *
+ * @param env           JNI environment
+ * @param java_string   Java String object
+ * @return              Newly allocated null-terminated standard UTF-8 C string, or NULL on error
+ */
+char *ff_jstring_to_utf8(JNIEnv *env, jstring java_string);