{"id":19572843,"url":"https://github.com/kirienko/gpx-player","last_synced_at":"2025-07-27T07:35:10.747Z","repository":{"id":178159746,"uuid":"661360733","full_name":"kirienko/gpx-player","owner":"kirienko","description":"Simple multiple GPX-tracks player, an open source alternative to Strava's Flyby","archived":false,"fork":false,"pushed_at":"2025-07-19T20:48:22.000Z","size":2319,"stargazers_count":8,"open_issues_count":3,"forks_count":4,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-07-19T23:01:48.402Z","etag":null,"topics":["gpx","gpx-parser","gpx-tracks","leaflet","openseamap","python","sailing"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kirienko.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-07-02T15:49:22.000Z","updated_at":"2025-06-29T13:09:04.000Z","dependencies_parsed_at":"2024-09-06T06:04:15.991Z","dependency_job_id":"8e19a145-62f6-4335-a4d8-8d82689a4651","html_url":"https://github.com/kirienko/gpx-player","commit_stats":null,"previous_names":["kirienko/gpx-player"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/kirienko/gpx-player","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kirienko%2Fgpx-player","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kirienko%2Fgpx-player/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kirienko%2Fgpx-player/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kirienko%2Fgpx-player/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kirienko","download_url":"https://codeload.github.com/kirienko/gpx-player/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kirienko%2Fgpx-player/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266042593,"owners_count":23867965,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gpx","gpx-parser","gpx-tracks","leaflet","openseamap","python","sailing"],"created_at":"2024-11-11T06:29:56.614Z","updated_at":"2025-07-27T07:35:10.741Z","avatar_url":"https://github.com/kirienko.png","language":"Python","funding_links":["https://www.buymeacoffee.com/kirienko"],"categories":[],"sub_categories":[],"readme":"# gpx-player\n## GPX Race Visualizer\n\nGPX Race Visualizer is a Python script to visualize the progression of multiple GPS tracks (e.g., from a race) on a 2D map. \nIt takes as input one or more GPX files and creates an animation showing the movement of each track over time. \nThis is a simple, open-source alternative to features like Strava's Flyby, which require an account and can have privacy issues.\n\n### Modes\nThe player supports two modes:\n#### 1. \"Video\" mode\nProduce an `MP4` or a `GIF` file showing how the situation developed.\nFor sailing races, it also calculates the distance covered after the 'start' signal and the current speed.\n##### Example:\n![Example output](example.gif \"Example of the script output\")\n\n#### 2. Map mode\nDisplays the track on OpenSeaMap.\nYou can see the full tracks with colour-coded speeds,\nand you can 'play' the tracks and see the markers move around the map. While playing, a legend shows each boat's distance travelled (in nautical miles), current speed (in knots), and average speed in knots.\n\n#### Example:\nSince GitHub Markdown doesn't allow embedding HTML, \nyou can see an [interactive example](https://kirienko.github.io/static/GinSul-2024.html) here.\n\nScreenshot:\n[![OPS Example](./example_osm.png)](https://kirienko.github.io/static/GinSul-2024.html)\n## Installation\n\nInstall directly from PyPI using pip:\n```bash\npip install gpx-player\n```\n\nAlternatively, clone the repository and install the required dependencies manually:\n```bash\ngit clone https://github.com/kirienko/gpx-player.git\ncd gpx-player\npip install -r requirements.txt\n```\n\n## Usage\nTo run the script producing `mp4`, pass one or more GPX file paths as command-line arguments:\n```bash\npython main.py example-data/track1.gpx example-data/track2.gpx\n```\nTo get a sea map, run the `openseamap.py`:\n```bash\npython openseamap.py --title 'Gin Sul Regatta 2024' --names Alex Yury Richard \\\n     --files example-data/osm-demo-Alex.gpx example-data/osm-demo-Richard.gpx \\\n             example-data/osm-demo-Yury.gpx\n```\n\nA more sophisticated example, that produced a video above:\n```bash\npython main.py example-data/track1.gpx example-data/track2.gpx example-data/track3.gpx \\\n       --start 2023-07-01T10:53:00+0000 \\\n       --names \"Mr. Pommeroy\" \"Miss Sophie\" \"Sir Toby²\" \\\n       --title \"Elbe-Damm Regatta (01.07.2023), Race 1\" \\\n       --race_start 2023-07-01T10:58:00+0000 --marks example-data/marks.txt -g\n```\n### Additional parameters:\n* `--title` or `-t`: The title of the video\n* `--start` or `-s`: start time in the format `2023-06-30T12:53:00+0200`, all points _before_ that will not be plotted\n* `--end` or `-e`: end time in the format `2023-06-30T13:53:00+0200`, all points _after_ that will not be plotted\n* `--names` or `-n`: names of the participants (otherwise the file names will be used in the legend)\n* `--race_start`, `-r`: Race start time in the format `YYYY-MM-DDTHH:MM:SS%z`, e.g. `2023-07-01T12:29:00+0200`\n* `--names` or `-n`: Names of the participants\n* `--marks`or`-m`: The file with the static marks to put onto the map. One pair of coordinates per line, see below.\n* `--gif` or `-g`: Save as GIF moving picture instead of MP4\n* `--timezone` or `-tz`: Local timezone to use for processing timestamps, e.g. `America/Los_Angeles`, see [here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) (default: `Europe/Berlin`).\n\n## Marks\nThe script also supports visualizing predefined marks on the map, which can be useful for events like sailing regattas.\nThe marks are defined as a list of (latitude, longitude) tuples in a separate text file and can be added to the script as follows:\n```\n53.542484632728, 9.801163896918299\n53.542997846049374, 9.80611324310303\n53.54823800356785, 9.812614917755129\n53.54921647691311, 9.807373881340029\n53.54508251196638, 9.80433225631714\n```\n\n## Getting GPX Files\n\nGPX files can be obtained from several GPS-tracking services:\n* Strava: Go to the activity page and click on the wrench icon. Then select \"Export GPX\".\n* Garmin Connect: Open the activity, go to the gear icon and select \"Export to GPX\".\n* Endomondo: From the workout page, click the three-dot menu icon and select \"Export\". Then choose \"GPX\".\n\n## GPX Validation\n\nFor the `gpx-player` to work properly, it needs the correct GPX files.\nYou can verify that you are inputting the correct file by using the special validator \nincluded in this package.\n\nThe `validator.py` script is a command-line utility and module for validating GPX files. \nIt checks for XML schema conformance and timestamp consistency, \nsupporting both strict and lenient modes. \nErrors are raised as `GPXValidationError` which can be caught in Python code. \nTo run as a CLI tool, use:\n```bash\npython validator.py path/to/yourfile.gpx --strict\n```\n\nThe `--strict` parameter is optional. In most cases you do not need it, \nbecause files that strictly correspond to the GPX schema are rare. \nFor example, almost all modern files contain coordinates, elevations and time stamps \nwith more decimal places than originally planned.\n\nAlso, to better understand your GPX file, you can use the `gpxinfo` console command \nthat comes with `gpxpy`. If you are already using the player, you have it:\n\n```bash\n$ gpxinfo example-data/osm_track1.gpx \nFile: example-data/osm_track1.gpx\n    Waypoints: 0\n    Routes: 0\n    Length 2D: 9.621km\n    Length 3D: 9.648km\n    Moving time: 01:05:22\n    Stopped time: n/a\n    Max speed: 3.12m/s = 11.22km/h\n    Avg speed: 2.46m/s = 8.85km/h\n    Total uphill: 97.20m\n    Total downhill: 98.40m\n    Started: 2024-07-24 15:59:05+00:00\n    Ended: 2024-07-24 17:04:27+00:00\n    Points: 776\n    Avg distance between points: 12.40m\n\n```\n\n## GPX Cleanup\n\nFor convenience, the repository provides `clean_gpx.py`. This utility first\nvalidates a GPX file using `validator.py` and then removes all `\u003cextensions\u003e`\nblocks using :func:`remove_extensions_tags` from `gpx_utils`. By default the\ncleaned file is saved alongside the original with `_noext` appended to its name.\nIf the optional `--overwrite` flag is used, the original file is modified in\nplace.\n\nRun it from the command line as follows:\n\n```bash\npython clean_gpx.py path/to/yourfile.gpx [--overwrite]\n```\n\nIf validation fails, the command exits with an error message. The output reports\nhow many extension blocks were removed.\n\n## Support\nNow you can buy me a coffee to encourage further development!\n\n[![\"Buy Me A Coffee\"](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://www.buymeacoffee.com/kirienko)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkirienko%2Fgpx-player","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkirienko%2Fgpx-player","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkirienko%2Fgpx-player/lists"}