Metadata-Version: 2.4
Name: freetar
Version: 0.19.0
Summary: an alternative frontend to ultimate-guitar.com
License-File: LICENSE
Author: kmille
Author-email: github@androidloves.me
Requires-Python: >=3.9
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: beautifulsoup4 (>=4.12.0,<5.0.0)
Requires-Dist: flask (>=3.0.30,<4.0.0)
Requires-Dist: flask-caching (>=2.3.1,<3.0.0)
Requires-Dist: flask-minify (>=0.50,<0.51)
Requires-Dist: requests[socks] (>=2.32.3,<3.0.0)
Requires-Dist: waitress (>=3.0.2,<4.0.0)
Project-URL: Homepage, https://github.com/freetar/freetar
Project-URL: Issues, https://github.com/freetar/freetar/issues
Project-URL: Repository, https://github.com/freetar/freetar
Description-Content-Type: text/markdown

# freetar - an open source alternative front-end to ultimate-guitar.com

This is like [Invidious](https://invidious.io/) but only for [Ultimate Guitar](https://www.ultimate-guitar.com/).  

## Instances
- https://freetar.de
- https://freetar.habedieeh.re
- https://tabs.adast.dk

## Features
- no ads, popups, AI, blockchain. Just a simple design
- search for tabs and view them
- save your favorite chords as favs (everything is stored in session storage (not send to the server), no account needed)
- dark mode
- auto scroll
- useful for printing chords
- show chords

## How to use it

After successful installation, there is an executable called `freetar` in the PATH. Execute it without parameters and it listens on 0.0.0.0:22000. You can specify a custom listen host or port by using environment variables. 

## Environment variables

* `FREETAR_HOST`
* `FREETAR_PORT`
* `FREETAR_CACHE_TIMEOUT` (how log should tabs be cached in memory, reduces the requests to Ultimate Guitar, defaults to 0 (inifnity))

**PyPi**  
Package: https://pypi.org/project/freetar/

```
pip install freetar
```

**Docker**  
Image: https://hub.docker.com/r/kmille2/freetar  
Port: 22000

```shell
sudo docker pull kmille2/freetar
sudo docker run -p 127.0.0.1:22000:22000 kmille2/freetar
```

Or use Docker compose:

```shell
sudo docker compose up -d
```

Set a custom bind port with the environment variable `FREETAR_PORT`

You can also build and run the local repository instead of pulling from Docker Hub:

```shell
docker compose build
docker compose up -d
```


### Dev environment
You need [uv](https://docs.astral.sh/uv/getting-started/installation/). Then:
```
FREETAR_CACHE_TIMEOUT=1 uv run freetar/backend.py
vim freetar/*.py
Visit localhost:22000 in browser

# static files: freetar/static/*
# html templates: freetar/templates/*
FREETAR_CACHE_TIMEOUT=1 uv run freetar
```

## Future work

- ~~show chords~~
- improve UX on mobile devices
- on smartphones: prevent lock screen
- package it as PGA (Progressive Web App)
- ~~share chords (qr code)?~~ (done by #12 with export/import functionality)
- save favs encrypted server side?
- ~~Browser Extension like [Invidious Redirection](https://addons.mozilla.org/en-US/firefox/addon/invidious-redirection/)~~ ([done](https://github.com/libredirect/browser_extension/issues/942))
- show qr code to quickly share a tab?

## Contributions

Feel free to contribute, but please create an issue before with a proposal of the feature. I don't want freetar to be bloated (neither UI nor functionality).

