Nomad: Mini WIFI Media Server

Hello Makers!

I’m Jackson Studner, a mechanical engineering student and hardware enthusiast who dove into coding, embedded systems, and web UI design through this project. Nomad is my first major software project, so do keep that in mind while setting it up. The devce serves as a portable offline media server powered by the ESP32-S3 microcontroller, designed to be compact, reliable, and fully open-source.

What is Jcorp Nomad?

Nomad is a self-contained, battery-friendly media server that fits in your pocket. It creates a local Wi-Fi hotspot with no internet connection needed, allowing you to stream your own movies, shows, music, books, and more directly from a microSD card. It’s perfect for camping, road trips, classrooms, or any scenario where connectivity is limited or unavailable.

This device functions similarly to popular media servers like Jellyfin but is fully offline, ultra-portable, and simple to use. It supports multiple simultaneous streams (tested with up to 8 videos at once), offers a customizable Screen UI via SquareLine Studio and LVGL, and works with most browser compatible devices, phones, laptops, tablets, etc. You can also easily edit the frontend on the go from the admin panel. My priorities where multi user support, simple and easy to understand frontend, and customizability. I wanted to design a blanket solution to fit the needs of many.

Why I Built This

As someone who loves camping and road trips, I frequently ran into problems with entertainment options. Streaming apps depend on cell signal and pre-downloading content can be restrictive or difficult to manage. Nomad solves this by letting you carry your own personal media server that anyone nearby can connect to, no cellular data, no cables, no fuss. It doesnt use accounts or an app, making the setup as quick as possible on any device (literaly just connect and use).

Key Features

1. Local captive-portal Wi‑Fi hotspot.
2. No user accounts, browser based tracking.
3. Browser-based UI: menu, movies, shows, music, books, gallery, files.
4. Admin panel: file browser (upload/rename/delete), shutdown, restart, flash mode, USB mass-storage, indexing controls, RGB and brightness controls, console logs + more.
5. Background, non-blocking library indexing.
6. Resume playback for movies & shows stored in browser cache.
7. Dark mode.
8. Improved show/music folder support (nested seasons, artist/album structure).
9. Music playlists, shuffle/loop, downloads.
10. EPUB and MP3 audiobook support.

Who Should Use Nomad?

1. Whether you’re a traveler, educator, parent, or hobbyist, Nomad offers a lightweight, offline media solution designed for maximum flexibility. It’s open source, so you can customize it or build your own version, no specialized skills required beyond basic hardware flashing and SD card management.

What You'll Need

Below is a general list of the hardware, software, and accessories you’ll need to complete the Jcorp Nomad project. I’ve included notes on options for customizing your build depending on your goals, whether you want to save money, maximize portability, or make it uniquely your own.

Note: The links below are Amazon affiliate links. If you click and buy something, I might earn a few cents—just enough to fund more SD cards and maybe one day a coffee that isn’t instant. Thanks for supporting the project (and keeping me caffeinated)!

Waveshare ESP32-S3 with 1.47" Display

Alternate link with better shipping times: Amazon Link (affiliate)

This all-in-one development board powers the entire project: Wi-Fi, display, and SD card support all on a single compact PCB. While it’s possible to build a Nomad using separate components, this board is by far the easiest, cleanest, and most space-efficient method.

MicroSD Card (16 GB or larger, Must be Grade 10)

I recommend at least 64 GB if you want to store a decent media library, but the system will work with as little as 16 GB if you only need a few files. Make sure to format the card as FAT32, ESP32 has compatibility issues with exFAT and NTFS.

The system is very read/write heavy so I highly recomend a Grade 10 micro SD card, as they are designed for the abuse, and you will see a notable performance increase using one.

If you’re feeling adventurous (or just absurdly wealthy), the project should support 1.5–2 TB SD cards. I haven’t tested those sizes yet, but if you do, please get in touch, I’d love to hear how that goes.

SD Card Extenders

These are not required, and sadly you can only bulk buy ones that are the right length (if I can find a different version I will update) The appeal of these is that you can access the SD card from the back of the case without removing it, making it a fair bit more clean. If you don't need to access the card often you can skip this part.

These will make it easier to access the SD card without disassembling the entire unit and improve durability.

3D Printed Case (Optional but Recommended)

Included in the project files is a 3D printable case for the project. This mainly serves to protect the screen as its not very durable and the sides / wiring can get damaged easily. You can glue the screen cover on, but in general it should be fine as a snap fit.

I highly recomend printing in PETG, the device can get hot and the plastic may warp if it's not heat tolerant.

Want to customize it? Add your name to the backplate, decals, ventilation holes, or accessory mounts. As a mechanical engineering student, I recommend trying TinkerCAD for easy 3D modeling. (not even a joke, love that software)

Software (All Free and Open Source)

1. SquareLine Studio – For editing the touchscreen UI using LVGL (this is advanced, but doable)
2. Arduino IDE – To compile and upload the firmware to the ESP32-S3
3. FAT32Format – For flashing the SD card into fat32 regardless of storage capacity
4. Web Browser – For testing the media portal and UI after flashing

All software tools used are free, cross-platform, and beginner-friendly. No professional coding experience is needed, if you can copy-paste, follow a few instructions, and tolerate some compile errors, you’ll do great.

My code isn’t perfect (it’s held together with duct tape and good vibes), but if you get stuck, feel free to drop a comment and I’ll try to help however I can! Also check out the discussions page on github, lots of documentation of past issues and ideas.

Get the Code and SD Card Layout

All source code, firmware, UI files, and a downloadable SD card template with the required folder structure and sample media are available here:

GitHub Repository: https://github.com/Jstudner/jcorp-nomad

Clone or download the repository to get started.

Before powering up Nomad, you’ll need to prepare the SD card with the correct folder structure, media files, and interface content. This is how your ESP32-S3 knows what to serve and how to present it to connected devices.

1. Important: The SD card must be formatted as FAT32, or the ESP32-S3 won’t be able to read it properly.

Formatting SD Cards

Windows won’t let you format cards larger than 32GB as FAT32 by default, but don't worry, there's a free and easy workaround.

Use the GUIFormat Tool:

1. Download the tool from https://fat32format-gui.en.lo4d.com/windows.
2. Insert your SD card into your computer and take note of what letter mount it used (such as /E)
3. Launch the guiformat.exe program.
4. Select your SD card’s drive letter.
5. Set:
6. Allocation size: 32K
7. Volume label: whatever you want!
8. Quick Format: ✅ Checked
9. Click Start. It’ll format the entire card as FAT32, even if it’s 64GB or 256GB.
10. Remember the key limitation of fat32 is that no single file can be bigger than 4GB

⚠️ Double-check that you selected the correct drive letter, this will erase everything on that card! ⚠️

Required Folder Structure

Here’s some examples of how you can layout your SD card:

A downloadable SD card template is included in the GitHub repository. You can download that directly to your SD card to get started. It includes sample media you can use to test before gathering all of your real content.

Requirements:

1. The Shows folder must contain subfolders for each show:

1. Inside each show folder, place the individual episode video files.
2. You can rename the media files to whatever you want, but it’s strongly recommended to use a consistent format like:

1. This helps keep the episodes in order (it sorts alphabetically).
2. You can also have season folders inside of the show folder with episodes in them. any video files placed outside of the seasons folder will be treated as a special or movie, and is also sorted alphabeticaly, allowing for it to be placed in watching order.

File Descriptions

Here’s what each of the key files does:

1. appleindex.html
2. This page is shown only on Apple devices (iPhones, iPads, etc.) due to how iOS handles captive portals. It includes special instructions for connecting and using the system.
3. index.html
4. This is the default homepage for all non-Apple devices. It automatically redirects based on device type. Handles all android based devices.
5. menu.html
6. The first screen users see after connecting. It displays links to Movies, Shows, Books, Music, Gallery, and Files. You can remove a section by editing this file and deleting its link (e.g., remove the “Books” link if you're not including books).
7. Has a search bar that can see all media files and will redirect to them.
8. At the bottom there is a section for resuming content from movies and shows. These items display on their pages as well.
9. books.html, movies.html, music.html, shows.html, gallery.html, and files.html
10. These are the individual section pages. They list the content available for each category. a search bar is included that uses in text search.
11. For Movies each video file should also get a matching jpg image with the exact same name. I recommend getting your Show and Movie Images from https://www.themoviedb.org/?language=en-US
12. For Shows each show gets one image, it should be in the /Shows directory and named the same as the directory that your episode files are in. Episodes and Seasons don't have images, it will just display the filename.
13. For Books I recomend using PDF, as it is the most stable. The system does support epub and mp3 audiobooks aswell though. Include a jpg cover image of the same name regardless of filetype.
14. For Music use mp3, wav, or flac files. You can also have subdirectories like with shows, items in the subdirectories will show on the main page, but also in sorted lists in the playlist page. Folders can be two levels deep, named however you want. /Music/Artist/Album/song.mp3 for example.
15. favicon.ico
16. The site’s tab icon. Replace it with your own if you like, but keep the same size and format.
17. Logo.png
18. Displayed on the site’s header. Feel free to swap it out with a logo of your own just use the same aspect ratio.

Admin Panel

Provides many useful tools for managing the system and customizing the experiance.

1. System controls: restart, shutdown, USB mode, and flash mode
2. Real-time monitoring: CPU temperature, connected users, and system status
3. RGB LED control: off/solid/rainbow modes with color picker
4. LCD brightness adjustment
5. Wi-Fi credentials management (SSID and password)
6. Admin password configuration with enable/disable options
7. Library indexing: manual full scan and auto-index on boot toggle
8. SD card storage usage tracking with visual progress bar
9. System console with real-time status monitoring
10. File browser with upload, rename, delete, and folder creation capabilities
11. Basic authentication system with password protection

What You Can Customize

You can edit any of the HTML or image files from the admin panel. Feel free to:

1. Change colors and layout in menu.html and section pages
2. Replace the logo, favicon, or placeholder image
3. Remove content categories (like Books or Music) by deleting the links in menu.html

Just remember: the system is expecting specific file and folder names, so don’t rename core files unless you know how to update the code to match.

Now that your SD card is ready, it’s time to upload the firmware to the ESP32-S3 board.

The Waveshare board used in this project makes things easy, it has a USB Type-A male connector, just like a flash drive. You can plug it directly into any available USB port on your laptop or PC, no adapters or extra cables required.

Installing Arduino IDE

If you haven’t already, download and install the Arduino IDE from:

https://www.arduino.cc/en/software

Once installed, open it up, you’ll use this to flash the Nomad firmware to the board.

Opening the Project

1. Download the firmware files from the GitHub page.
2. Open the .ino file in Arduino IDE.
3. Ensure you download all of the files in the "firmware/JcorpNomadProject" directory, when you run the ino those files need to be preset for it to function.
4. The project should load all necessary tabs and files automatically. (if they don't load check its in the right spot as above)

Board Setup in Arduino IDE

You’ll need to tell Arduino IDE how to talk to the ESP32 board. Follow these steps:

1. Go to File > Preferences
2. Under "Additional Board Manager URLs", paste this:

1. Then go to Tools > Board > Board Manager
2. Search for and install “esp32 by Espressif Systems”

Now configure the board under the "Tools" Tab, look for the following settings towards the bottom and set them as follows:

1. Board: ESP32S3 Dev Module
2. Port: Select the correct COM port once the device is plugged in
3. USB CDC on Boot > Enabled
4. Flash Size: 16MB (128Mb)
5. Partition Scheme: 16MB Flash (3MB APP/9.9MB FATFS)
6. PSRAM: OPI PSRAM
7. Upload Speed: 921600
8. USB Mode: USB-OTG (tinyUSB)

⚠️ These settings are based on the Waveshare 1.47" display model, other boards may need adjustments. Also check the picture of the settings above. ⚠️

Required Libraries

Go to "tools" > "Manage Libraries"

You will need to install the following Libraries/Versions through the library manager:

1. "ArduinoJson" by Benoit Blanchon v7.3.0
2. "Async TCP" by ESP32Async v3.4.7
3. "ESP Async Webserver" by ESP32Async v3.7.1
4. "LVGL" by kisvegabor v8.4.0

Make sure you use the correct versions as they are required!

Flashing the Code

Once everything is set:

1. Click the Upload (right arrow) button in Arduino IDE.
2. Wait for the compile and upload process to finish.
3. If successful, you’ll see a “Done uploading” message.
4. Check the serial output to see if everything launched correctly. There will be debugging logs for your convenience.

If you get errors, make sure the correct COM port is selected and the board is seated properly. Try pressing the boot/reset button on the ESP32 if needed during upload. For missing library errors

A guide for this ESP32 board can be found at This Link, it may help troubleshooting.

You can also check to see if anyone has had similar problems, or open a new issue on the github here.

If you need to get the ESP32S3 back into Flash Mode:

You can manually put the device in flashing mode if Arduino IDE stops picking it up on serial. This can happen if you need to re-flash the code at any point, as once Nomad is loaded, the device will no longer accept flash writes unless put into Flash mode. If you can access the web server, you can simply click "Flash Mode" in the admin panel. If you can't access the web server, you can do it with the two onboard buttons by holding the BOOT button, pressing the RESET button, then release the RESET button and then finally release the BOOT button. The screen should go dark, or say "Flash mode".

Editing the screen UI

1. You can change what displays on the screen, currently it displays a SD usage bar, the current SSID, # of connected users, and WIFI/SD card status.
2. Editing the screen will involve downloading Squareline studios and using the free version to edit the files in the github.
3. This isnt super beginer friendly, but you can find docs for squareline online and the project files are avaiable on the github under /docs.

Library issues:

1. If you encounter an error while flashing along the lines of: fatal error: <libraryname>.h: No such file or directory
2. It usually means your libraries are the wrong version. I recommend cleaning out everything in your library folder (usually C:\Users\<yourusername>\Documents\Arduino\libraries on windows) and updating with just the required ones.
3. Then try to re-flash, it should work.

Once your ESP32-S3 board has been flashed and tested, you can enclose it in the 3D-printed case. I strongly recommend waiting until after you’ve verified the device is fully working before snapping the case together, It should come apart, but the more often you do it the weaker the tabs will get.

Heads-Up Before You Start:

1. The front screen is very fragile I broke several during development, the case is intended to protect it so be very gentle when installing it, I recommend starting from the USB side and pressing down gently while sliding it backwards with the far side from the USB going on last. The new design is more forgiving, but still be careful adding and removing it.
2. Test everything before assembling. Seriously. Connect to the Wi-Fi, open the menu, stream a file, only then move on to the case.
3. If you are not confident in your printers acuracy I recomend printing 1% larger (scale it to 101%) and if its loose you can allways go down.

🔥 About Heat

This device runs hot. Like, really hot. The ESP32-S3 chip and SD card area can get toasty under load, especially when multiple people are streaming content. Quality PLA shouldnt warp, but if you can get PETG use it!

Here’s how to keep it cool:

1. Add a tiny thermal pad or dab of thermal paste between the ESP32-S3 chip and the case shell
2. Keep an eye on SD card health, high temps can shorten their lifespan, using a quality card will help greatly, the SD extender also helps to reduce heat exposure.
3. Cutting down a few office staples makes a good heatsink
4. Keep in mind I just aircool mine without issues, no thermal paste or anything, its not going to explode, but depends on your goals / prefomance. all of the testing has been done air cooled.

So far I haven’t burned out a board, but I wouldn’t rule it out either. Just plan for heat, and you’ll be fine.

Let’s be real, how you get your media is up to you. Personally, I rip my own DVDs and Blu-rays, which gives me full control over the format and quality. But however you source your movies, shows, music, and ebooks, there are some important formatting rules and optimization tips you’ll want to follow to make everything work smoothly on Nomad.

Supported Formats (Very Important)

The ESP32-S3 isn’t exactly a media powerhouse, so we have to keep things lightweight and consistent.

1. Movies & Shows: .mp4, .mov, .mkv, .webm
2. Keep resolution and bitrate modest (more on this below)
3. Music: .mp3, .flac, .wav
4. Books: .pdf, .epub, .mp3
5. Images: .jpg
6. Each Movie, Show folder, and Book should have a matching .jpg file for the poster/cover image

Tip: There’s an included script called img.py that you can run to compress all .jpg files in a folder. It helps save space and keeps load times fast. (smaller images load quicker in the web UI)

Optimize Videos with HandBrake

HandBrake is an awesome free tool for converting and compressing videos. I use it to prep almost all of my media for Nomad.

Why compress?

1. Lower file size = faster load & more streams at once!
2. Avoids crashes during playback
3. Saves SD card space = more media
4. ensure files are under the 4GB file limit

🔧 Recommended HandBrake Settings

1. Open HandBrake and drag your video file in, or select a folder with multiple and queue them.
2. Under Format, choose: MP4 (or any of the compatible types)
3. Under Video tab:
4. Preset: Fast 480p (check web optimized on)
5. Video Codec: H.264 (x264)
6. Framerate (FPS): Same as source, Constant Framerate
7. Quality: Use the RF slider, set it to around 22–24 for a good size/quality balance
8. Under Audio tab:
9. Keep a single stereo track, AAC codec
10. Under Subtitles:
11. Burn In any you need.
12. If you don't burn them in (say for anime) they will not show up. so be sure to do this if you need it.
13. File naming:
14. For episodes, I recommend naming like:
15. S01E01 - The Pilot.mp4
16. Keeping things alphabetized will prevent playback order issues, the index sorts alphabetically so plan for that.

Once you're happy with your settings, click "Start Encode" and you’re good to go. For more detailed steps check online, handbrake is widely used and well documented. If you are in a rush or have tons of files (or just willing to use more space just doing the fast 480p preset and web optimizing is usually fine for most uses.

It is also worth noting nomad will suport higher quality video files, just at the cost of performance. It very much depends on the encoding, but under (very) ideal conditions I have gotten Big Buck Bunny (common 10min demo vid) to play at 4k 60FPS, with minimal buffering) though of course this limits the device to one stream at a time and isnt recomended.

Clean Folder Structure

Nomad depends on a specific folder and file layout to function properly. Here’s what it should look like:

Naming Tips

1. Keep file names simple and clean (avoid emojis, long symbols, or extra punctuation)
2. For shows, using SxxExx - Title helps avoid weird sorting issues
3. Covers must match the name of the main media file/folder (e.g., Interstellar.mp4 + Interstellar.jpg)

Thanks for Checking Out the Jcorp Nomad Project!

What started as a quick side project has turned into months of tinkering, debugging, and learning new skills I never expected to pick up. I didn’t originally plan to publish this, so it’s been amazing to see how much interest it’s gotten.

Nomad works well today, but there’s still plenty I want to add, and plenty of room for others to take it further. Some ideas in the pipeline:

1. Offline Maps – Inspired by the Backcountry Beacon project, store map tiles on the SD card so you can see your position without cell service. I’ve tested a few approaches, but it’s not quite nailed down yet.
2. Retro Game Emulation – Using emulatorJS to support ROMs and other games that can be run fully in a web browser.
3. Custom CSS - Control styles similar to jellyfin.
4. Chat Page - Similar to pirate box's chat feature, works as a message board for connected users
5. Whiteboard page - lets you draw, but also has a shared board that all connected users can see / work on.

If you decide to build your own version of Nomad, I’d love to see it. Share photos, fork the repo, or drop a comment if you get stuck or come up with a cool feature idea. This project is open source so others can help it grow in ways I can’t on my own.

Happy hacking ✌️

— Jackson Studner

Links:

Github

Buy a Prebuilt (please just build one)

Portfolio Site (WIP)