diff --git a/.github/images/card-view.png b/.github/images/card-view.png index e9f670ab..61471e7a 100644 Binary files a/.github/images/card-view.png and b/.github/images/card-view.png differ diff --git a/.github/images/folders.png b/.github/images/folders.png index a756e02b..9587b82d 100644 Binary files a/.github/images/folders.png and b/.github/images/folders.png differ diff --git a/.github/images/pre-v1.5.0/card-view.png b/.github/images/pre-v1.5.0/card-view.png new file mode 100644 index 00000000..e9f670ab Binary files /dev/null and b/.github/images/pre-v1.5.0/card-view.png differ diff --git a/.github/images/edit-details.png b/.github/images/pre-v1.5.0/edit-details.png similarity index 100% rename from .github/images/edit-details.png rename to .github/images/pre-v1.5.0/edit-details.png diff --git a/.github/images/pre-v1.5.0/folders.png b/.github/images/pre-v1.5.0/folders.png new file mode 100644 index 00000000..a756e02b Binary files /dev/null and b/.github/images/pre-v1.5.0/folders.png differ diff --git a/.github/images/list-view.png b/.github/images/pre-v1.5.0/list-view.png similarity index 100% rename from .github/images/list-view.png rename to .github/images/pre-v1.5.0/list-view.png diff --git a/.github/images/login-screen.png b/.github/images/pre-v1.5.0/login-screen.png similarity index 100% rename from .github/images/login-screen.png rename to .github/images/pre-v1.5.0/login-screen.png diff --git a/.github/images/mobile-view.png b/.github/images/pre-v1.5.0/mobile-view.png similarity index 100% rename from .github/images/mobile-view.png rename to .github/images/pre-v1.5.0/mobile-view.png diff --git a/.github/images/pre-v1.5.0/ogg-data.png b/.github/images/pre-v1.5.0/ogg-data.png new file mode 100644 index 00000000..a7586149 Binary files /dev/null and b/.github/images/pre-v1.5.0/ogg-data.png differ diff --git a/.github/images/preview-modal.png b/.github/images/pre-v1.5.0/preview-modal.png similarity index 100% rename from .github/images/preview-modal.png rename to .github/images/pre-v1.5.0/preview-modal.png diff --git a/.github/images/uploading.png b/.github/images/pre-v1.5.0/uploading.png similarity index 100% rename from .github/images/uploading.png rename to .github/images/pre-v1.5.0/uploading.png diff --git a/.github/images/watch-page.png b/.github/images/pre-v1.5.0/watch-page.png similarity index 100% rename from .github/images/watch-page.png rename to .github/images/pre-v1.5.0/watch-page.png diff --git a/README.md b/README.md index b100c57f..110ac5cb 100644 --- a/README.md +++ b/README.md @@ -33,335 +33,178 @@

- -
- Table of Contents -
    -
  1. - About The Project - -
    2. -
  2. Changelog
    3. -
  3. - Installation - -
    4. -
  4. - Local Development - -
    5. -
  5. Contributing
    6. -
  6. - FAQ / Troubleshooting - -
    7. -
-
+## Key Features - +- Share videos through unique links +- Public / Private feeds (private is link only) +- Game-based organization with cover art +- Uploads (optional, can be restricted) +- Video view counting +- Open Graph metadata for rich link previews +- RSS feed for new public videos +- LDAP support +- Optional video transcoding with CPU or NVIDIA GPU -# About The Project +

Dashboard

-I create a lot of game clips with tools such as Nvidia's Shadowplay, many of these clips are short 15-30 second clips that I want to share with my friends but do not want to spend the time uploading them to YouTube, waiting for YouTube to process the video and then finally being able to send them a link. - -I thought that there had to be a simple solution that allowed me the ability to self host my clips and share them with my friends through some generated link? Unfortunately nothing I found was quite what I was looking for. So with the help of a friend we quickly built Fireshare to do just that. - -The goal of Fireshare is to provide a very simple and easy way for you to share any videos you have through a unique link. All you have to do is put your videos in a folder and Fireshare will take care of the rest. - -![login-screen] - -

The Dashboard

-

Here you can see all of your videos and edit their details such as title, description and whether or not you want them to show up on the public feed.

- -![card-view] - -

Maybe card view isn't your style? Fireshare also supports a list style view as well.

- -![list-view] - -

NEW! Automatic Organizing by Games

-

Organize your video clips by games so you know exactly where they are. Fireshare can automatically scan and organize your video clips by games, and organize them with beautiful and relevant cover art.

-Gamestab - -

Uploading

-

Allow your community or the public the ability to upload videos. Of course, this feature can be disabled or limited to only administrator access

- -![uploading] - -

Edit Video Details

-

Access a basic modal for editing the title and description of videos by clicking on the "pencil" icon.

- -![edit-details] - -

Video Preview Modal

-

Videos opened when on the public feed or admin dashboard show up in a modal. This modal gives you direct link and timestamped link sharing buttons as well as the ability to "shuffle" randomly to another video. As an admin, you can also edit the details of the video from this modal.

- -![preview-modal] - -

The Watch Page

-

This is what people will see when given a Fireshare link.

- -![watch-page] +--- -

Mobile Support

-

-Prefer to browse on your mobile device? No problem. Fireshare has you covered. -

+![card-view][card-view] -

+

Automatic Game Organization

-

Open Graph Support

-

-Direct links copied from the link copy buttons in Fireshare will allow websites and messaging apps to read the open graph data and show title, description and video thumbnails in your posts. -

-

-Logo -

-

RSS Feed Support

-

- Stay up to date in your favorite RSS reader. Fireshare publishes a feed of the - latest public videos so you can subscribe and get new uploads automatically. -

+--- +![folders][folders] -

LDAP Authentication Support

-

-Connect Fireshare to a central user directory and keep user access organised. -

- -### Built With +

Open Graph Support

-- [React](https://reactjs.org/) -- [Python](https://www.python.org/) -- [Material UI](https://mui.com/) +--- - +
Open graph preview
-# Installation +## Installation -Fireshare is meant to run within a Docker environment. While we reccommend using something like Docker Compose it is not required and can run with a simple `docker run` command. +Fireshare is designed to run in Docker. -Fireshare needs 3 volume mounts. +Required mounts: -1. **/data** - The directory used by fireshare to hold its internal database -2. **/processed** - The directory used to hold metadata created by fireshare in relation to your videos (posters, metadata info) -3. **/videos** - The directory fireshare will watch and scan for any videos. +1. `/data` - internal database +2. `/processed` - generated metadata (posters, metadata files) +3. `/videos` - source video directory to scan -If you have all of your game clips stored in a folder **my_game_clips** then in your docker compose file (or docker run command) you will need to volume mount that folder to the **/videos** folder that fireshare watches. +If your clips are in `/path/to/my_game_clips/`, mount that path to `/videos` in the container. ### Docker Compose -If you have docker compose installed, at the root of this project you can simply run this command. +Edit `docker-compose.yml` for your host paths and admin credentials, then run: -> **make sure you edit the docker-compose.yml** file with your volume locations and admin password. - -``` +```sh docker-compose up -d ``` -### Docker - -``` -docker run --name fireshare -v $(pwd)/fireshare:/data:rw -v $(pwd)/fireshare_processed:/processed:rw -v /path/to/my_game_clips:/videos:rw -p 8080:80 -e ADMIN_PASSWORD=your-admin-password -d shaneisrael/fireshare:latest -``` - -Once running, navigate to `localhost:8080` in your browser. +Then open `http://localhost:8080`. -### Configurable Settings +### Docker Run -See the Fireshare Configuration Wiki: Link -For LDAP configuration, see [LDAP.md](./LDAP.md) +```sh +docker run --name fireshare \ + -v $(pwd)/fireshare:/data:rw \ + -v $(pwd)/fireshare_processed:/processed:rw \ + -v /path/to/my_game_clips:/videos:rw \ + -p 8080:80 \ + -e ADMIN_PASSWORD=your-admin-password \ + -d shaneisrael/fireshare:latest +``` -### Video Transcoding (Optional) -Fireshare supports automatic transcoding of your videos to create multiple quality variants. This feature is **disabled by default** and must be enabled via environment variables. +Open `http://localhost:8080`. -Screenshot 2026-02-11 at 9 36 56 AM +## Configuration +- LDAP setup: [LDAP.md](./LDAP.md) -**Benefits:** -- Smaller file sizes with AV1 compression (up to 50% smaller than H.264) -- Better streaming performance for users with limited bandwidth -- Quality selection in the video player -- Only videos larger than the target resolution are transcoded -- Original files are never modified or deleted +### Transcoding (Optional) -**How to Enable** -- Add `ENABLE_TRANSCODING=true` to your environment variables -- CPU transcoding works out of the box - no additional setup required -- Manage transcoding from the **Settings** page in the settings page +Transcoding is off by default. -**Environment Variables:** ```yaml -# Enable transcoding (default: false) ENABLE_TRANSCODING=true - -# Optional: Enable GPU acceleration (default: false) -# Requires NVIDIA GPU setup - see below -TRANSCODE_GPU=true +TRANSCODE_GPU=true # optional, NVIDIA only ``` ---- +CPU transcoding works out of the box. For NVIDIA GPU setup with the Docker image, you only need an NVIDIA GPU on the host—the image handles drivers and toolkit. -### GPU Transcoding (Optional) +#### GPU Requirements -GPU transcoding is **optional** but provides 5-10x faster encoding if you have an NVIDIA GPU. CPU transcoding works out of the box without any of this setup. +- NVIDIA GPU with NVENC support -**Requirements:** -- NVIDIA GPU with NVENC support (GTX 1050+ / Pascal or newer) -- NVIDIA drivers installed on the host system -- NVIDIA Container Toolkit: https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html +#### Unraid Setup -**Docker Compose GPU Setup:** -```yaml -services: - fireshare: - # ... other configuration ... - environment: - - ENABLE_TRANSCODING=true - - TRANSCODE_GPU=true - - NVIDIA_DRIVER_CAPABILITIES=all - runtime: nvidia - deploy: - resources: - reservations: - devices: - - driver: nvidia - count: 1 - capabilities: [gpu] -``` - -**Verify GPU Access:** -```bash -docker exec -it fireshare ffmpeg -encoders 2>/dev/null | grep nvenc -``` - -**Unraid GPU Setup:** +If you're using Unraid: 1. Install "NVIDIA Driver" plugin from Apps/Community Applications -2. Add environment variables to the Fireshare container: +2. Add to Fireshare container environment: ``` ENABLE_TRANSCODING=true TRANSCODE_GPU=true NVIDIA_DRIVER_CAPABILITIES=all ``` -3. In "Extra Parameters", add: `--gpus=all` +3. Add to "Extra Parameters": `--gpus=all` -**Transcoding Fallback Chain:** +#### Encoder Selection -The system automatically selects the best available encoder: +When GPU mode is enabled, Fireshare selects the best available encoder: **GPU Mode** (`TRANSCODE_GPU=true`): -1. AV1 with GPU (av1_nvenc) - RTX 40 series or newer -2. H.264 with GPU (h264_nvenc) - GTX 1050+ -3. AV1 with CPU - fallback if GPU encoding fails -4. H.264 with CPU - final fallback + +- AV1 with GPU (av1_nvenc) — RTX 40 series or newer +- H.264 with GPU (h264_nvenc) — GTX 1050+ +- Fallback to CPU encoders if GPU encoding fails **CPU Mode** (`TRANSCODE_GPU=false`): -1. H.264 with CPU - Most compatible, faster encoding -2. AV1 with CPU - best compression, slower on CPU -# Local Development +- H.264 with CPU — Most compatible, faster encoding +- AV1 with CPU — Best compression, slower -If you would like to run Fireshare via the source code in order to contribute you will need to have npm, Node.js and Python installed. I reccommend installing Node.js with NVM so that you can easily switch between Node versions. +## Local Development -### Setup +Requirements: Python 3, Node.js, and npm. -1. Have Python3, NodeJS and NPM installed. -2. Clone the repo +1. Clone the repo: ```sh - $ git clone https://github.com/ShaneIsrael/fireshare.git + git clone https://github.com/ShaneIsrael/fireshare.git ``` -3. At the project root +2. Start backend services from project root: ```sh - $ ./run_local.sh + ./run_local.sh ``` -4. In a new terminal, navigate to `app/client` and run the following commands. - ```JS - $ npm i && npm start +3. Start frontend: + ```sh + cd app/client + npm install + npm start ``` -5. In your browser, navigate to `localhost:3000` and login with admin/admin - - - -# Contributing - -If this project is at all interesting to you please feel free to contribute or create suggestions if you have them. Please note that creating a pull request does not guarantee it will be accepted into the project. Outside of obvious bug fixes it may be best to consult with us before starting work on any additions you'd like to make. - -[For questions or feature requests please create an issue with an appropriate label here](https://github.com/ShaneIsrael/fireshare/issues/new) - -1. Fork the Project -2. Add upstream (`git remote add upstream https://github.com/ShaneIsrael/fireshare.git`) -3. Create your Feature Branch (`git checkout -b feature/AmazingFeature`) -4. Commit your Changes (`git commit -m 'Add some AmazingFeature'`) -5. Rebase with upstream (`git rebase upstream/main`) -6. Fix any merge conflicts you may have -7. Push to the Branch (`git push origin feature/AmazingFeature`) -8. Open a Pull Request against the **develop** branch - -**UPDATE YOUR BRANCH** We will not fix merge conflicts for you, if you make a pull request and it states there are merge conflicts please see steps 4 and 5 from the above. +4. Open `http://localhost:3000` and sign in with `admin/admin`. -### Updating the Fireshare Database +## Contributing -If you need to update the database or add a new table / column first make your changes to the `app/server/fireshare/models.py` file then at the root of the project run `flask db migrate -m "name of migration"` a new migration will be made with your changes. Go to that file and double check that everything is correct. You may need to manually edit this migration. +Contributions are welcome. For larger changes, open an issue first to align on scope. -# Frequently Asked Questions +1. Fork the repository +2. Create a branch from `develop` +3. Commit your changes +4. Rebase on latest `develop` +5. Open a pull request to `develop` -### Playback Issues +Issues and feature requests: https://github.com/ShaneIsrael/fireshare/issues -If you are experiencing playback issues there could be a number of reasons as to why. These are the most common causes. +### Database Changes -1. **File Size** +If you update models, create a migration and review it before opening a pull request. - Fireshare serves your videos as they are. If your videos are very large anybody trying to watch will need to have a fast enough download speed to play them back. This also means you will need to have an upload speed fast enough to serve your large files. Consider using a tool like Handbrake to compress your videos down to a smaller size. +## Troubleshooting -2. **Upload Speed** +### Playback Problems - Your upload speed matters. If you have a slow upload speed, depending the file sizes that you are trying to serve it may not be possible for people to stream your videos. Consider compressing your videos with Handbrake. +If playback is unstable: -3. **Browsers** +- Reduce source file size/bitrate +- Verify upload bandwidth on the host +- Prefer browser-friendly formats (MP4/H.264 is safest) +- Consider enabling transcoding for better compatibility +- Test in another browser to rule out codec/browser limitations - In my testing I have noticed that Firefox struggles to playback very large files, however Chome and Edge do not seem to have the same problem. +### Upload Fails Behind Nginx -4. **Unsupported File Type** +Increase proxy limits/timeouts, for example: - At the moment, Fireshare only supports file types and encodings that browsers can play natively, generally MP4, MOV and WEBM files. For example you could have h265 encoded videos work just fine and play in chrome, but not play at all in Firefox which wouldn't be a great experience for your viewers. It's reccommended to use MP4 encoded in h264 where possible since it is supported by virtually every browser at this time. If your video file does not play or causes errors you may need to transcode it to an h264 encoded MP4 with a tool like Handbrake. - -5. **Upload Issues** - - Uploading issues are often caused by putting fireshare behind some sort of reverse proxy like nginx. By default nginx has limits on how large your uploads can be. Often the issue is that your trying to upload a file larger than nginx allows. You'll need to update your reverse proxies settings to increase these limits and timeouts. If you are using nginx, you most likely just need to add these two lines. - - ``` - client_max_body_size 0; - proxy_read_timeout 999999s; - ``` +```nginx +client_max_body_size 0; +proxy_read_timeout 999999s; +``` - These settings will only work on Nginx. With `client_max_body_size` set to `0` we are allowing any size upload. We are also increasing the timeout limit so that the connection isn't timedout. If you are not using nginx you'll need to do some research. +If you use a different proxy, apply equivalent upload size and timeout settings there. - - +--- -[contributors-shield]: https://img.shields.io/github/contributors/ShaneIsrael/fireshare.svg?style=for-the-badge -[contributors-url]: https://github.com/ShaneIsrael/fireshare/graphs/contributors -[forks-shield]: https://img.shields.io/github/forks/ShaneIsrael/fireshare.svg?style=for-the-badge -[forks-url]: https://github.com/ShaneIsrael/fireshare/network/members -[stars-shield]: https://img.shields.io/github/stars/ShaneIsrael/fireshare.svg?style=for-the-badge -[stars-url]: https://github.com/ShaneIsrael/fireshare/stargazers -[issues-shield]: https://img.shields.io/github/issues/ShaneIsrael/fireshare.svg?style=for-the-badge -[issues-url]: https://github.com/ShaneIsrael/fireshare/issues [card-view]: .github/images/card-view.png -[edit-details]: .github/images/edit-details.png [folders]: .github/images/folders.png -[login-screen]: .github/images/login-screen.png -[list-view]: .github/images/list-view.png -[preview-modal]: .github/images/preview-modal.png -[watch-page]: .github/images/watch-page.png -[ogg-data]: .github/images/ogg-data.png -[mobile-view]: .github/images/mobile-view.png -[uploading]: .github/images/uploading.png