Config SmooSense to display media files and access S3

1. Displaying images/videos#

1.1 Relative or absolute path on your local computer#

Assuming you have table file and folder structure as below

/Users/xxx/Downloads/
├── table.parquet
└── images
   ├── one.jpg
   ├── two.jpg
   └── three.jpg

Then you can use relative path (based on the table file), or absolute path to display images/videos. Here is one example:

Note that the relative path must start with ./ and absolute path must start with /.

1.2 Raw bytes#

If your data contains raw media bytes (e.g. image or video binary data in a BLOB column), SmooSense automatically detects the media type from magic bytes and renders them inline. Supported formats include JPEG, PNG, GIF, WebP, BMP, TIFF, MP4, AVI, MKV, WAV, MP3, FLAC, OGG, and PDF.

No extra configuration is needed — just store the binary data in your table and SmooSense will handle the rest.

1.3 Media bytes in HuggingFace format#

If your data uses the HuggingFace datasets format for media columns, SmooSense also supports that. The column value should be a struct with bytes and path fields:

{"bytes": b"\x89PNG...", "path": "image.png"}

This works for images, audio, and video.

The path field must have a recognized file extension (e.g. .jpg, .png, .mp4, .wav). SmooSense uses it to determine the MIME type and how to render the media. Without a valid extension, the content will not be displayed.

1.4 Public url#

For public data, you can expose them as urls and put the url in table cells. For example:

http://images.cocodataset.org/train2017/000000211189.jpg

1.5 On AWS S3 or S3-compatible storage#

Full S3 url is also supported. For example:

s3://bucket/path/to/file.jpg

Note that you need to setup AWS S3 authentication. See below.

3 Customized private urls#

If you data is private, you can run an API to proxy the url. On the server side, use cookie to authenticate requests.

Make sure the url ends with an image extension (e.g. .jpg) for it to be treated as image url. The same for video.

2. S3 authentication#

2.1 AWS S3#

It is recommended to setup your AWS credentials using AWS CLI v2.

If you use default profile or set credentials using AWS_* environment variables, you can simply run sense to start SmooSense.

sense # I will pick up global AWS config

To use a profile, run

AWS_PROFILE=xxx sense

2.2 S3-compatible storage#

Other blob storages that support boto3 sdk are also supported. You need to provide the endpoint url for that storage. Below is an example for CloudFlare R2 storage:

AWS_ENDPOINT_URL=https://<account-id>.r2.cloudflarestorage.com AWS_PROFILE=r2 sense

3. Customized private urls#

If you data is private, you can run an API to proxy the url. On the server side, use cookie to authenticate requests.

Make sure the url ends with an image extension (e.g. .jpg) for it to be treated as image url. The same for video.

4. Run with a specific port number and url prefix#

sense --port 8888 --url-prefix /subpath