Source   Edit  

FileTable

File index and metadata management for FAT filesystems on Daisy hardware.

This module provides a utility for creating an indexed table of files from a directory, with support for filtering, sorting, and metadata access. Commonly used for managing audio sample libraries (.wav files) on SD cards.

What is FileTable?

FileTable scans a directory on an SD card or QSPI flash, builds an in-memory index of files, and provides fast access to file names and sizes.

Typical use cases:

• Loading .wav sample libraries
• Managing preset/patch files
• Building a file browser UI
• Batch file operations

Key features:

• Alphabetical sorting (case-insensitive)
• File extension filtering (e.g., only ".wav" files)
• Fixed-size table (compile-time capacity)
• Metadata access (file name, size)
• Log file generation for debugging

Basic Usage

Step 1: Define table capacity

# Create table for up to 64 files
type SampleTable = FileTable[64]

var samples: SampleTable

Step 2: Scan directory

# Load all .wav files from /samples/ directory
if samples.fill("/samples", ".wav"):
  echo "Found ", samples.getNumFiles(), " .wav files"
else:
  echo "Error scanning directory"

Step 3: Access file info

for i in 0..<samples.getNumFiles():
  let name = samples.getFileName(i)
  let size = samples.getFileSize(i)
  echo i, ": ", name, " (", size, " bytes)"

Complete Example

Sample player with SD card library:

import nimphea_filetable
import nimphea/per/sdmmc

type SampleLibrary = FileTable[128]

var samples: SampleLibrary
var sd: SdmmcHandler

proc loadSampleLibrary() =
  # Initialize SD card
  sd.init()
  
  if not samples.fill("/samples", ".wav"):
    echo "Error: Could not scan samples directory"
    return
  
  echo "Sample Library:"
  echo "---------------"
  
  for i in 0..<samples.getNumFiles():
    if samples.isFileInSlot(i):
      let name = samples.getFileName(i)
      let size = samples.getFileSize(i)
      echo i + 1, ". ", name, " (", size, " bytes)"
  
  # Optional: Write log file to SD card
  if samples.writeLog("/samples_index.txt"):
    echo "Index written to samples_index.txt"

Filtering Files

Example 1: Load only .wav files

samples.fill("/audio", ".wav")

Example 2: Load only .txt files

presets.fill("/presets", ".txt")

Example 3: Load all files (no filter)

allFiles.fill("/data", nil)  # nil = no extension filter

File Access Patterns

Pattern 1: Iterate all files

for i in 0..<samples.getNumFiles():
  let filename = samples.getFileName(i)
  processSample(filename)

Pattern 2: Check if slot has file

if samples.isFileInSlot(5):
  let name = samples.getFileName(5)
  echo "Slot 5: ", name
else:
  echo "Slot 5 is empty"

Pattern 3: Find file by name

proc findFile(table: var SampleTable, searchName: cstring): int =
  for i in 0..<table.getNumFiles():
    if table.getFileName(i) == searchName:
      return i
  return -1

let idx = findFile(samples, "kick.wav")
if idx >= 0:
  echo "Found at index ", idx

Load/Save State Management

FileTable includes optional flags for coordinating file I/O operations:

Save workflow:

# User presses "Save" button
samples.setSavePending(3)  # Mark slot 3 for saving

# In main loop
if samples.isSavePending():
  let slot = samples.getSlotForSaveLoad()
  let filename = samples.getFileName(slot)
  saveDataToFile(filename)
  samples.clearSavePending()

Load workflow:

# User selects file 7
samples.setLoadPending(7)

# In main loop
if samples.isLoadPending():
  let slot = samples.getSlotForSaveLoad()
  let filename = samples.getFileName(slot)
  loadDataFromFile(filename)
  samples.clearLoadPending()

Log File Generation

Generate a text file listing all indexed files (useful for debugging):

samples.fill("/samples", ".wav")
samples.writeLog("/samples_log.txt")

Example log file output:

1:  kick.wav    45632 bytes
2:  snare.wav   38912 bytes
3:  hihat.wav   12048 bytes

Capacity and Limitations

Compile-time capacity:

The table size is fixed at compile time via the template parameter:

type
  SmallTable = FileTable[16]   # Max 16 files
  MediumTable = FileTable[64]  # Max 64 files
  LargeTable = FileTable[256]  # Max 256 files

Memory usage:

Each slot uses ~260 bytes (255 chars for filename + size field).

FileTable[16]:  ~4KB RAM
FileTable[64]:  ~16KB RAM
FileTable[256]: ~64KB RAM

Filename length:

Maximum filename length is 255 characters (FAT long filename support).

What happens when table is full?

fill() stops after loading max_slots files. Remaining files are ignored. Use a larger table size if needed.

Sorting Behavior

Files are automatically sorted alphabetically (case-insensitive) after loading:

Directory contents:    Sorted in table:
- snare.wav            1. bass.wav
- kick.wav             2. hihat.wav
- Bass.wav             3. kick.wav
- HiHat.wav            4. snare.wav

Case-insensitive: "Bass.wav" and "bass.wav" are treated equally.

Error Handling

Check return values:

if not samples.fill("/samples", ".wav"):
  echo "ERROR: Could not scan directory"
  echo "Possible causes:"
  echo "- SD card not mounted"
  echo "- Directory does not exist"
  echo "- Filesystem error"
  return

if samples.getNumFiles() == 0:
  echo "WARNING: No .wav files found in /samples/"

Performance Notes

• Scanning is relatively slow (depends on number of files)
• Call fill() once during initialization, not in main loop
• Accessing file metadata (name, size) is instant (in-memory lookup)
• Sorting adds minimal overhead (insertion sort, ~O(n²) but n is small)

See Also

• per/sdmmc - SD card access
• per/qspi - QSPI flash access
• FatFs documentation - Underlying filesystem library

Compile-time examples (not executable without hardware) All examples use discard to avoid compile errors in test mode