SF3

An implementation of SF3 (Simple File Format Family) in Rust. See the spec at https://shirakumo.org/docs/sf3

[!WARNING] This crate is experimental, and a work-in-progress. Expect major breaking changes until v1.0.

Feedback is appreciated, either via an issue or contacting me directly!

Features

This crate is a work-in-progress. The following functions have been implemented and tested:

• Read SF3 files from bytes in memory, a file on disc, or any std::io::Read reader
• Read metadata or headers alone, for easy parsing of large files
• Create new SF3 files of supported formats
• MIME types and preferred file extensions for all supported formats
• no_std support
• Formats
  • Archive
  • Audio
  • Text
  • ...

Roadmap

The following formats have yet to be implemented:

• Image
• Log (and a mechanism for efficiently appending to a Log file)
• Model
• Physics-Model
• Table (serde serializer?)
• Vector Graphic

Examples

See the examples directory. Run an example using cargo run --example <example>

Dependencies

• Stable Rust (2024 edition)
• chrono for parsing timestamp values (see the Archive file type)
• const-str and const_panic for constructing sized strings from string literals
• crc32fast for computing CRC32 checksums
• half for handling 16-bit floats until f16 stabilizes (see the Audio file type)
• mediatype for parsing and serving MIME types
• timeout-readwrite for ensuring File I/O doesn't hang when it should time out

Usage

Parse from memory:

use sf3::file::Sf3File;
use sf3::Archive;

let archive_bytes: &[u8] = /* ... */;
let archive = Archive::parse_bytes(archive_bytes).unwrap();
assert_eq!(archive.payload.len(), 2);

Parse from file:

use sf3::file::Sf3File;
use sf3::Archive;

let file = std::fs::File::open("/path/to/example.ar.sf3")?;
let archive = Archive::parse_file(file).unwrap();
assert_eq!(archive.payload.len(), 2);

Parse from Reader or custom buffer:

use sf3::file::Sf3File;
use sf3::Archive;

let stream: impl std::io::Read = /* ... */;
let buf = std::io::BufReader::new(stream);
let archive = Archive::parse_io(Box::new(buf)).unwrap();
assert_eq!(archive.payload.len(), 2);

MIME type (const compatible):

use mediatype::MediaType;

// mime-types for specific formats
let archive_type: MediaType = sf3::Archive::MIME;
let audio_type: MediaType = sf3::Archive::MIME;

// mime-type for a general SF3 file (may change in future with IANA registration)
let sf3_type: MediaType = sf3::file::MIME;

Feature flags

std

This feature is enabled by default, and enables support for parsing files from Read types, and certain features in chrono, const-str, crc32fast, and half which require Rust's std crate. All functions work well enough without std, including parsing from byte slices and generating new byte representations of SF3 files, so if you're writing a no_std crate or targeting an environment where std isn't available but alloc and core are, then you may disable this feature without much consequence.

serde

Disabled by default. Enables serde support for chrono, half, and mediatype types.

Testing

Run code-coverage tests using the test.sh script.

Regular unit tests can be run using cargo test. Use the --no-default-features flag to test no_std support.

The tests/ directory contains sample files to test against. These are copied directly from the Shirakumo/sf3 repository, and may be out of date.

Contributing

Suggestions and code contributions are welcome! The codebase lives primarily at git.average.name, where you may file issues or pull requests using a fresh account there or an existing account with Codeberg or the like.

A read-only code mirror of this project also exists at Codeberg.

Acknowledgements

The SF3 spec was written by Yukari Hafner at Shirakumo, under the zlib License.

The API was somewhat inspired by the yaml and toml crates.