rayohx-cli 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (99) hide show
  1. rayohx_cli-0.1.0/.gitignore +49 -0
  2. rayohx_cli-0.1.0/.python-version +1 -0
  3. rayohx_cli-0.1.0/CHANGELOG.md +28 -0
  4. rayohx_cli-0.1.0/LICENSE +201 -0
  5. rayohx_cli-0.1.0/PKG-INFO +92 -0
  6. rayohx_cli-0.1.0/README.md +68 -0
  7. rayohx_cli-0.1.0/docs/architecture.md +75 -0
  8. rayohx_cli-0.1.0/docs/development.md +79 -0
  9. rayohx_cli-0.1.0/docs/guides/cli/clean.md +34 -0
  10. rayohx_cli-0.1.0/docs/guides/cli/config.md +18 -0
  11. rayohx_cli-0.1.0/docs/guides/cli/download.md +307 -0
  12. rayohx_cli-0.1.0/docs/guides/cli/exit-codes.md +76 -0
  13. rayohx_cli-0.1.0/docs/guides/cli/global-options.md +64 -0
  14. rayohx_cli-0.1.0/docs/guides/cli/info.md +197 -0
  15. rayohx_cli-0.1.0/docs/guides/cli/settings.md +115 -0
  16. rayohx_cli-0.1.0/docs/guides/cli.md +137 -0
  17. rayohx_cli-0.1.0/docs/packaging.md +79 -0
  18. rayohx_cli-0.1.0/docs/security.md +37 -0
  19. rayohx_cli-0.1.0/pyproject.toml +79 -0
  20. rayohx_cli-0.1.0/src/rayohx_cli/__init__.py +3 -0
  21. rayohx_cli-0.1.0/src/rayohx_cli/__main__.py +6 -0
  22. rayohx_cli-0.1.0/src/rayohx_cli/cli/__init__.py +26 -0
  23. rayohx_cli-0.1.0/src/rayohx_cli/cli/clean.py +59 -0
  24. rayohx_cli-0.1.0/src/rayohx_cli/cli/common.py +108 -0
  25. rayohx_cli-0.1.0/src/rayohx_cli/cli/config.py +82 -0
  26. rayohx_cli-0.1.0/src/rayohx_cli/cli/download.py +262 -0
  27. rayohx_cli-0.1.0/src/rayohx_cli/cli/info.py +121 -0
  28. rayohx_cli-0.1.0/src/rayohx_cli/cli/lifecycle.py +190 -0
  29. rayohx_cli-0.1.0/src/rayohx_cli/cli/root.py +105 -0
  30. rayohx_cli-0.1.0/src/rayohx_cli/events.py +40 -0
  31. rayohx_cli-0.1.0/src/rayohx_cli/format.py +34 -0
  32. rayohx_cli-0.1.0/src/rayohx_cli/output.py +119 -0
  33. rayohx_cli-0.1.0/src/rayohx_cli/params/__init__.py +147 -0
  34. rayohx_cli-0.1.0/src/rayohx_cli/params/display.py +35 -0
  35. rayohx_cli-0.1.0/src/rayohx_cli/params/engine.py +106 -0
  36. rayohx_cli-0.1.0/src/rayohx_cli/params/network.py +227 -0
  37. rayohx_cli-0.1.0/src/rayohx_cli/params/output.py +77 -0
  38. rayohx_cli-0.1.0/src/rayohx_cli/params/panels.py +7 -0
  39. rayohx_cli-0.1.0/src/rayohx_cli/params/selection.py +187 -0
  40. rayohx_cli-0.1.0/src/rayohx_cli/progress/__init__.py +24 -0
  41. rayohx_cli-0.1.0/src/rayohx_cli/progress/_factory.py +20 -0
  42. rayohx_cli-0.1.0/src/rayohx_cli/progress/_text.py +47 -0
  43. rayohx_cli-0.1.0/src/rayohx_cli/progress/reporters/__init__.py +8 -0
  44. rayohx_cli-0.1.0/src/rayohx_cli/progress/reporters/bar.py +60 -0
  45. rayohx_cli-0.1.0/src/rayohx_cli/progress/reporters/base.py +19 -0
  46. rayohx_cli-0.1.0/src/rayohx_cli/progress/reporters/null.py +16 -0
  47. rayohx_cli-0.1.0/src/rayohx_cli/progress/reporters/plain.py +38 -0
  48. rayohx_cli-0.1.0/src/rayohx_cli/py.typed +0 -0
  49. rayohx_cli-0.1.0/src/rayohx_cli/render.py +122 -0
  50. rayohx_cli-0.1.0/src/rayohx_cli/settings.py +78 -0
  51. rayohx_cli-0.1.0/src/rayohx_cli/values.py +284 -0
  52. rayohx_cli-0.1.0/tests/__init__.py +0 -0
  53. rayohx_cli-0.1.0/tests/conftest.py +143 -0
  54. rayohx_cli-0.1.0/tests/fixtures/ladder.m3u8 +9 -0
  55. rayohx_cli-0.1.0/tests/fixtures/single_segment.m3u8 +5 -0
  56. rayohx_cli-0.1.0/tests/frozen.py +38 -0
  57. rayohx_cli-0.1.0/tests/helpers/__init__.py +0 -0
  58. rayohx_cli-0.1.0/tests/helpers/cli.py +33 -0
  59. rayohx_cli-0.1.0/tests/helpers/console.py +35 -0
  60. rayohx_cli-0.1.0/tests/helpers/media.py +8 -0
  61. rayohx_cli-0.1.0/tests/helpers/params.py +79 -0
  62. rayohx_cli-0.1.0/tests/helpers/progress.py +55 -0
  63. rayohx_cli-0.1.0/tests/helpers/servers.py +156 -0
  64. rayohx_cli-0.1.0/tests/helpers/site.py +59 -0
  65. rayohx_cli-0.1.0/tests/integration/__init__.py +0 -0
  66. rayohx_cli-0.1.0/tests/integration/test_cli_entrypoint.py +110 -0
  67. rayohx_cli-0.1.0/tests/integration/test_frozen_cli.py +53 -0
  68. rayohx_cli-0.1.0/tests/unit/__init__.py +0 -0
  69. rayohx_cli-0.1.0/tests/unit/cli/__init__.py +0 -0
  70. rayohx_cli-0.1.0/tests/unit/cli/test_clean_and_config.py +153 -0
  71. rayohx_cli-0.1.0/tests/unit/cli/test_common.py +86 -0
  72. rayohx_cli-0.1.0/tests/unit/cli/test_download.py +325 -0
  73. rayohx_cli-0.1.0/tests/unit/cli/test_download_many.py +125 -0
  74. rayohx_cli-0.1.0/tests/unit/cli/test_info.py +188 -0
  75. rayohx_cli-0.1.0/tests/unit/cli/test_lifecycle.py +182 -0
  76. rayohx_cli-0.1.0/tests/unit/cli/test_local_and_events.py +102 -0
  77. rayohx_cli-0.1.0/tests/unit/cli/test_root.py +218 -0
  78. rayohx_cli-0.1.0/tests/unit/params/__init__.py +0 -0
  79. rayohx_cli-0.1.0/tests/unit/params/test_display.py +44 -0
  80. rayohx_cli-0.1.0/tests/unit/params/test_engine.py +137 -0
  81. rayohx_cli-0.1.0/tests/unit/params/test_network.py +167 -0
  82. rayohx_cli-0.1.0/tests/unit/params/test_output.py +138 -0
  83. rayohx_cli-0.1.0/tests/unit/params/test_panels.py +51 -0
  84. rayohx_cli-0.1.0/tests/unit/params/test_selection.py +136 -0
  85. rayohx_cli-0.1.0/tests/unit/progress/__init__.py +0 -0
  86. rayohx_cli-0.1.0/tests/unit/progress/reporters/__init__.py +0 -0
  87. rayohx_cli-0.1.0/tests/unit/progress/reporters/test_bar.py +112 -0
  88. rayohx_cli-0.1.0/tests/unit/progress/reporters/test_base.py +46 -0
  89. rayohx_cli-0.1.0/tests/unit/progress/reporters/test_null.py +27 -0
  90. rayohx_cli-0.1.0/tests/unit/progress/reporters/test_plain.py +100 -0
  91. rayohx_cli-0.1.0/tests/unit/progress/test_factory.py +70 -0
  92. rayohx_cli-0.1.0/tests/unit/progress/test_text.py +119 -0
  93. rayohx_cli-0.1.0/tests/unit/test_dependencies.py +43 -0
  94. rayohx_cli-0.1.0/tests/unit/test_format.py +41 -0
  95. rayohx_cli-0.1.0/tests/unit/test_main.py +19 -0
  96. rayohx_cli-0.1.0/tests/unit/test_output.py +231 -0
  97. rayohx_cli-0.1.0/tests/unit/test_render.py +257 -0
  98. rayohx_cli-0.1.0/tests/unit/test_settings.py +89 -0
  99. rayohx_cli-0.1.0/tests/unit/test_values.py +290 -0
@@ -0,0 +1,49 @@
1
+ # OS files
2
+ .DS_Store
3
+ Thumbs.db
4
+ desktop.ini
5
+
6
+ # Editors and IDEs
7
+ .idea/
8
+ .vscode/
9
+ *.swp
10
+ *.swo
11
+ *~
12
+
13
+ # Environment and secrets
14
+ .env
15
+ .env.*
16
+ !.env.example
17
+ *.pem
18
+ *.key
19
+
20
+ # Logs and temporary files
21
+ *.log
22
+ *.tmp
23
+ *.bak
24
+
25
+ # Claude Code local settings
26
+ .claude/settings.local.json
27
+
28
+
29
+ # Python
30
+ __pycache__/
31
+ *.py[cod]
32
+ .venv/
33
+ build/
34
+ dist/
35
+ *.egg-info/
36
+ .mypy_cache/
37
+ .ruff_cache/
38
+ .pytest_cache/
39
+ .hypothesis/
40
+ .schemathesis/
41
+ .coverage
42
+ .coverage.*
43
+ htmlcov/
44
+ coverage.xml
45
+
46
+ .temp/
47
+
48
+ # Node (rayohx_ui/ui); its build output is covered by dist/ above
49
+ node_modules/
@@ -0,0 +1 @@
1
+ 3.11
@@ -0,0 +1,28 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/).
4
+
5
+ ## [Unreleased]
6
+
7
+ ### Added
8
+
9
+ - `rayohx clean` removes leftover working folders, and `rayohx config` shows the settings in effect.
10
+ - `--playlist-file` on `download` and `info` reads a playlist you already have from a file instead of fetching it, and `--base-url` sets the address its relative links resolve against. A local playlist file can also be given in place of the address.
11
+ - `--events` writes every download event as one JSON line on stderr, for other programs.
12
+ - Tune retries and redirects (`--backoff`, `--max-redirects`), sign in to a proxy (`--proxy-username`, `--proxy-password`) and read cookies from a browser's `cookies.txt` (`--cookie-file`).
13
+ - `--directory` picks the folder to save into, `--reserve-space` keeps some disk space free, and `--no-keep-state` clears what a resume needs after a failure.
14
+ - Press P (or the space bar) during a download to pause it, and again to resume. On Linux and macOS, `kill -USR1` does the same.
15
+ - `rayohx download` accepts several addresses, or a list in a file with `--input-file` (`-` reads standard input). `--output` then names a folder, and `--stop-on-error` stops at the first failure.
16
+ - `--allow-file-keys` lets a stream's local key files be read; streams with keys inside the playlist now download.
17
+ - Prefer a video codec (`--codec`) or dynamic range (`--video-range`), and cap the frame rate (`--max-frame-rate`), when choosing a stream.
18
+ - SOCKS5 proxies, `--env-proxy` to use the proxy environment variables, and client certificates for mutual TLS (`--client-cert`, `--client-key`, `--client-key-password`).
19
+ - The `rayohx` command: `rayohx info URL` shows a stream's qualities and tracks and what a download would pick, and `rayohx download URL` saves it as one file.
20
+ - Choose what to download: a quality (`--quality`, `--max-resolution`, `--max-bitrate`), a stream exactly (`--variant N` from `rayohx info`, counting from 1, `--resolution 1280x720`, `--bandwidth`, `--variant-name`), and audio and subtitle tracks (`--audio`, `--subtitles`, `--video-only`).
21
+ - Choose how to save: `--format` (`auto`, `ts`, `mp4` or one file per segment), `--overwrite` and `--validate`. FFmpeg is optional (`--ffmpeg`, `--remux-backend`).
22
+ - Network options for protected streams: headers, cookies, user agent, referer, origin, a proxy, TLS settings (`--insecure`, `--ca-bundle`), timeouts, retries and a rate limit. Secret values can be read from a file with `@file`, and credentials go only to the stream's own host and the hosts you list.
23
+ - Interrupted downloads continue where they stopped when you run the same command again, and Ctrl-C stops one cleanly.
24
+ - A progress bar (or plain lines), `--json` output for other programs, `--quiet`, `--verbose` and `--no-color`, and `--log-file` with secrets removed.
25
+ - Defaults from a `rayohx.toml` settings file (or `--config`) and `RAYOHX_` environment variables, with exit codes 0, 1, 2 and 130.
26
+ - `--no-space-check` turns off the disk-space check, for drives that report free space wrongly.
27
+ - A Windows setup (with an optional `PATH` entry) and a portable zip, and Linux `.deb` and `.rpm` packages for x86_64 and ARM64 with an icon.
28
+ - The command is also available as the `rayohx-cli` package.
@@ -0,0 +1,201 @@
1
+ Apache License
2
+ Version 2.0, January 2004
3
+ http://www.apache.org/licenses/
4
+
5
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
6
+
7
+ 1. Definitions.
8
+
9
+ "License" shall mean the terms and conditions for use, reproduction,
10
+ and distribution as defined by Sections 1 through 9 of this document.
11
+
12
+ "Licensor" shall mean the copyright owner or entity authorized by
13
+ the copyright owner that is granting the License.
14
+
15
+ "Legal Entity" shall mean the union of the acting entity and all
16
+ other entities that control, are controlled by, or are under common
17
+ control with that entity. For the purposes of this definition,
18
+ "control" means (i) the power, direct or indirect, to cause the
19
+ direction or management of such entity, whether by contract or
20
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
21
+ outstanding shares, or (iii) beneficial ownership of such entity.
22
+
23
+ "You" (or "Your") shall mean an individual or Legal Entity
24
+ exercising permissions granted by this License.
25
+
26
+ "Source" form shall mean the preferred form for making modifications,
27
+ including but not limited to software source code, documentation
28
+ source, and configuration files.
29
+
30
+ "Object" form shall mean any form resulting from mechanical
31
+ transformation or translation of a Source form, including but
32
+ not limited to compiled object code, generated documentation,
33
+ and conversions to other media types.
34
+
35
+ "Work" shall mean the work of authorship, whether in Source or
36
+ Object form, made available under the License, as indicated by a
37
+ copyright notice that is included in or attached to the work
38
+ (an example is provided in the Appendix below).
39
+
40
+ "Derivative Works" shall mean any work, whether in Source or Object
41
+ form, that is based on (or derived from) the Work and for which the
42
+ editorial revisions, annotations, elaborations, or other modifications
43
+ represent, as a whole, an original work of authorship. For the purposes
44
+ of this License, Derivative Works shall not include works that remain
45
+ separable from, or merely link (or bind by name) to the interfaces of,
46
+ the Work and Derivative Works thereof.
47
+
48
+ "Contribution" shall mean any work of authorship, including
49
+ the original version of the Work and any modifications or additions
50
+ to that Work or Derivative Works thereof, that is intentionally
51
+ submitted to Licensor for inclusion in the Work by the copyright owner
52
+ or by an individual or Legal Entity authorized to submit on behalf of
53
+ the copyright owner. For the purposes of this definition, "submitted"
54
+ means any form of electronic, verbal, or written communication sent
55
+ to the Licensor or its representatives, including but not limited to
56
+ communication on electronic mailing lists, source code control systems,
57
+ and issue tracking systems that are managed by, or on behalf of, the
58
+ Licensor for the purpose of discussing and improving the Work, but
59
+ excluding communication that is conspicuously marked or otherwise
60
+ designated in writing by the copyright owner as "Not a Contribution."
61
+
62
+ "Contributor" shall mean Licensor and any individual or Legal Entity
63
+ on behalf of whom a Contribution has been received by Licensor and
64
+ subsequently incorporated within the Work.
65
+
66
+ 2. Grant of Copyright License. Subject to the terms and conditions of
67
+ this License, each Contributor hereby grants to You a perpetual,
68
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
69
+ copyright license to reproduce, prepare Derivative Works of,
70
+ publicly display, publicly perform, sublicense, and distribute the
71
+ Work and such Derivative Works in Source or Object form.
72
+
73
+ 3. Grant of Patent License. Subject to the terms and conditions of
74
+ this License, each Contributor hereby grants to You a perpetual,
75
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
76
+ (except as stated in this section) patent license to make, have made,
77
+ use, offer to sell, sell, import, and otherwise transfer the Work,
78
+ where such license applies only to those patent claims licensable
79
+ by such Contributor that are necessarily infringed by their
80
+ Contribution(s) alone or by combination of their Contribution(s)
81
+ with the Work to which such Contribution(s) was submitted. If You
82
+ institute patent litigation against any entity (including a
83
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
84
+ or a Contribution incorporated within the Work constitutes direct
85
+ or contributory patent infringement, then any patent licenses
86
+ granted to You under this License for that Work shall terminate
87
+ as of the date such litigation is filed.
88
+
89
+ 4. Redistribution. You may reproduce and distribute copies of the
90
+ Work or Derivative Works thereof in any medium, with or without
91
+ modifications, and in Source or Object form, provided that You
92
+ meet the following conditions:
93
+
94
+ (a) You must give any other recipients of the Work or
95
+ Derivative Works a copy of this License; and
96
+
97
+ (b) You must cause any modified files to carry prominent notices
98
+ stating that You changed the files; and
99
+
100
+ (c) You must retain, in the Source form of any Derivative Works
101
+ that You distribute, all copyright, patent, trademark, and
102
+ attribution notices from the Source form of the Work,
103
+ excluding those notices that do not pertain to any part of
104
+ the Derivative Works; and
105
+
106
+ (d) If the Work includes a "NOTICE" text file as part of its
107
+ distribution, then any Derivative Works that You distribute must
108
+ include a readable copy of the attribution notices contained
109
+ within such NOTICE file, excluding those notices that do not
110
+ pertain to any part of the Derivative Works, in at least one
111
+ of the following places: within a NOTICE text file distributed
112
+ as part of the Derivative Works; within the Source form or
113
+ documentation, if provided along with the Derivative Works; or,
114
+ within a display generated by the Derivative Works, if and
115
+ wherever such third-party notices normally appear. The contents
116
+ of the NOTICE file are for informational purposes only and
117
+ do not modify the License. You may add Your own attribution
118
+ notices within Derivative Works that You distribute, alongside
119
+ or as an addendum to the NOTICE text from the Work, provided
120
+ that such additional attribution notices cannot be construed
121
+ as modifying the License.
122
+
123
+ You may add Your own copyright statement to Your modifications and
124
+ may provide additional or different license terms and conditions
125
+ for use, reproduction, or distribution of Your modifications, or
126
+ for any such Derivative Works as a whole, provided Your use,
127
+ reproduction, and distribution of the Work otherwise complies with
128
+ the conditions stated in this License.
129
+
130
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
131
+ any Contribution intentionally submitted for inclusion in the Work
132
+ by You to the Licensor shall be under the terms and conditions of
133
+ this License, without any additional terms or conditions.
134
+ Notwithstanding the above, nothing herein shall supersede or modify
135
+ the terms of any separate license agreement you may have executed
136
+ with Licensor regarding such Contributions.
137
+
138
+ 6. Trademarks. This License does not grant permission to use the trade
139
+ names, trademarks, service marks, or product names of the Licensor,
140
+ except as required for reasonable and customary use in describing the
141
+ origin of the Work and reproducing the content of the NOTICE file.
142
+
143
+ 7. Disclaimer of Warranty. Unless required by applicable law or
144
+ agreed to in writing, Licensor provides the Work (and each
145
+ Contributor provides its Contributions) on an "AS IS" BASIS,
146
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
147
+ implied, including, without limitation, any warranties or conditions
148
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
149
+ PARTICULAR PURPOSE. You are solely responsible for determining the
150
+ appropriateness of using or redistributing the Work and assume any
151
+ risks associated with Your exercise of permissions under this License.
152
+
153
+ 8. Limitation of Liability. In no event and under no legal theory,
154
+ whether in tort (including negligence), contract, or otherwise,
155
+ unless required by applicable law (such as deliberate and grossly
156
+ negligent acts) or agreed to in writing, shall any Contributor be
157
+ liable to You for damages, including any direct, indirect, special,
158
+ incidental, or consequential damages of any character arising as a
159
+ result of this License or out of the use or inability to use the
160
+ Work (including but not limited to damages for loss of goodwill,
161
+ work stoppage, computer failure or malfunction, or any and all
162
+ other commercial damages or losses), even if such Contributor
163
+ has been advised of the possibility of such damages.
164
+
165
+ 9. Accepting Warranty or Additional Liability. While redistributing
166
+ the Work or Derivative Works thereof, You may choose to offer,
167
+ and charge a fee for, acceptance of support, warranty, indemnity,
168
+ or other liability obligations and/or rights consistent with this
169
+ License. However, in accepting such obligations, You may act only
170
+ on Your own behalf and on Your sole responsibility, not on behalf
171
+ of any other Contributor, and only if You agree to indemnify,
172
+ defend, and hold each Contributor harmless for any liability
173
+ incurred by, or claims asserted against, such Contributor by reason
174
+ of your accepting any such warranty or additional liability.
175
+
176
+ END OF TERMS AND CONDITIONS
177
+
178
+ APPENDIX: How to apply the Apache License to your work.
179
+
180
+ To apply the Apache License to your work, attach the following
181
+ boilerplate notice, with the fields enclosed by brackets "[]"
182
+ replaced with your own identifying information. (Don't include
183
+ the brackets!) The text should be enclosed in the appropriate
184
+ comment syntax for the file format. We also recommend that a
185
+ file or class name and description of purpose be included on the
186
+ same "printed page" as the copyright notice for easier
187
+ identification within third-party archives.
188
+
189
+ Copyright 2026 coldsofttech
190
+
191
+ Licensed under the Apache License, Version 2.0 (the "License");
192
+ you may not use this file except in compliance with the License.
193
+ You may obtain a copy of the License at
194
+
195
+ http://www.apache.org/licenses/LICENSE-2.0
196
+
197
+ Unless required by applicable law or agreed to in writing, software
198
+ distributed under the License is distributed on an "AS IS" BASIS,
199
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
200
+ See the License for the specific language governing permissions and
201
+ limitations under the License.
@@ -0,0 +1,92 @@
1
+ Metadata-Version: 2.5
2
+ Name: rayohx-cli
3
+ Version: 0.1.0
4
+ Summary: RayoHX command line (the rayohx command).
5
+ Project-URL: Homepage, https://github.com/coldsofttech/RayoHX
6
+ Project-URL: Issues, https://github.com/coldsofttech/RayoHX/issues
7
+ Project-URL: Changelog, https://github.com/coldsofttech/RayoHX/blob/main/CHANGELOG.md
8
+ Author: coldsofttech
9
+ License-Expression: Apache-2.0
10
+ License-File: LICENSE
11
+ Classifier: Programming Language :: Python :: 3
12
+ Classifier: Programming Language :: Python :: 3.11
13
+ Classifier: Programming Language :: Python :: 3.12
14
+ Classifier: Programming Language :: Python :: 3.13
15
+ Classifier: Programming Language :: Python :: 3.14
16
+ Classifier: Programming Language :: Python :: 3.15
17
+ Classifier: Typing :: Typed
18
+ Requires-Python: >=3.11
19
+ Requires-Dist: click>=8.5.1
20
+ Requires-Dist: rayohx
21
+ Requires-Dist: rich>=13.9
22
+ Requires-Dist: typer>=0.29.1
23
+ Description-Content-Type: text/markdown
24
+
25
+ # RayoHX command line
26
+
27
+ [![CI](https://github.com/coldsofttech/RayoHX/actions/workflows/ci.yml/badge.svg)](https://github.com/coldsofttech/RayoHX/actions/workflows/ci.yml)
28
+ [![PyPI](https://img.shields.io/pypi/v/rayohx-cli)](https://pypi.org/project/rayohx-cli/)
29
+ [![Python versions](https://img.shields.io/pypi/pyversions/rayohx-cli)](https://pypi.org/project/rayohx-cli/)
30
+ [![Typer](https://img.shields.io/badge/Typer-CLI-black)](https://typer.tiangolo.com/)
31
+ [![Rich](https://img.shields.io/badge/output-Rich-blue)](https://github.com/Textualize/rich)
32
+ [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
33
+ [![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
34
+ [![License](https://img.shields.io/github/license/coldsofttech/RayoHX)](LICENSE)
35
+
36
+ `rayohx` downloads HLS streams (`.m3u8`) to a file from your terminal.
37
+
38
+ ```sh
39
+ rayohx info https://cdn.example.com/vod/master.m3u8
40
+ rayohx download https://cdn.example.com/vod/master.m3u8 -o movie.mp4
41
+ ```
42
+
43
+ `info` shows what a stream offers; `download` saves it. The saved file's path is the only thing
44
+ printed on stdout, so it is easy to use in a script.
45
+
46
+ ## What you can do
47
+
48
+ - See a stream's qualities, audio and subtitle tracks and encryption before downloading anything
49
+ - Choose the quality, audio and subtitles, and download to a file or a folder of segments
50
+ - Download encrypted (AES-128) streams; protected (DRM) and live streams are refused with an
51
+ explanation
52
+ - Join a separate audio track into one MP4, with nothing re-encoded
53
+ - Continue interrupted downloads where they stopped
54
+ - Download several streams with one command, from addresses or a list file (`--input-file`)
55
+ - Use a playlist you already have, from a file, instead of fetching it (`--playlist-file`, `--base-url`)
56
+ - Follow a download from another program with `--events`
57
+ - Watch a progress bar, or get machine-readable output with `--json`
58
+ - Keep settings in a file or `RAYOHX_` environment variables
59
+ - Use `--verbose`, `--quiet`, `--no-color` and shell completion
60
+ - Download several streams at once, read local playlist files, and clean up after interrupted downloads
61
+
62
+ ## Install
63
+
64
+ Requires Python 3.11 or newer. Install it in its own isolated environment:
65
+
66
+ ```sh
67
+ uv tool install rayohx-cli
68
+ ```
69
+
70
+ or with pipx:
71
+
72
+ ```sh
73
+ pipx install rayohx-cli
74
+ ```
75
+
76
+ Check it works:
77
+
78
+ ```sh
79
+ rayohx --version
80
+ ```
81
+
82
+ ## Learn more
83
+
84
+ - [Command line guide](https://github.com/coldsofttech/RayoHX/blob/main/docs/guides/cli.md): every
85
+ option, settings, exit codes and examples
86
+ - [Changelog](CHANGELOG.md)
87
+ - Using it from Python instead? See the [`rayohx`](https://pypi.org/project/rayohx/) library
88
+ - [Report a problem](https://github.com/coldsofttech/RayoHX/issues)
89
+
90
+ ## License
91
+
92
+ Apache-2.0. See [LICENSE](LICENSE).
@@ -0,0 +1,68 @@
1
+ # RayoHX command line
2
+
3
+ [![CI](https://github.com/coldsofttech/RayoHX/actions/workflows/ci.yml/badge.svg)](https://github.com/coldsofttech/RayoHX/actions/workflows/ci.yml)
4
+ [![PyPI](https://img.shields.io/pypi/v/rayohx-cli)](https://pypi.org/project/rayohx-cli/)
5
+ [![Python versions](https://img.shields.io/pypi/pyversions/rayohx-cli)](https://pypi.org/project/rayohx-cli/)
6
+ [![Typer](https://img.shields.io/badge/Typer-CLI-black)](https://typer.tiangolo.com/)
7
+ [![Rich](https://img.shields.io/badge/output-Rich-blue)](https://github.com/Textualize/rich)
8
+ [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
9
+ [![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
10
+ [![License](https://img.shields.io/github/license/coldsofttech/RayoHX)](LICENSE)
11
+
12
+ `rayohx` downloads HLS streams (`.m3u8`) to a file from your terminal.
13
+
14
+ ```sh
15
+ rayohx info https://cdn.example.com/vod/master.m3u8
16
+ rayohx download https://cdn.example.com/vod/master.m3u8 -o movie.mp4
17
+ ```
18
+
19
+ `info` shows what a stream offers; `download` saves it. The saved file's path is the only thing
20
+ printed on stdout, so it is easy to use in a script.
21
+
22
+ ## What you can do
23
+
24
+ - See a stream's qualities, audio and subtitle tracks and encryption before downloading anything
25
+ - Choose the quality, audio and subtitles, and download to a file or a folder of segments
26
+ - Download encrypted (AES-128) streams; protected (DRM) and live streams are refused with an
27
+ explanation
28
+ - Join a separate audio track into one MP4, with nothing re-encoded
29
+ - Continue interrupted downloads where they stopped
30
+ - Download several streams with one command, from addresses or a list file (`--input-file`)
31
+ - Use a playlist you already have, from a file, instead of fetching it (`--playlist-file`, `--base-url`)
32
+ - Follow a download from another program with `--events`
33
+ - Watch a progress bar, or get machine-readable output with `--json`
34
+ - Keep settings in a file or `RAYOHX_` environment variables
35
+ - Use `--verbose`, `--quiet`, `--no-color` and shell completion
36
+ - Download several streams at once, read local playlist files, and clean up after interrupted downloads
37
+
38
+ ## Install
39
+
40
+ Requires Python 3.11 or newer. Install it in its own isolated environment:
41
+
42
+ ```sh
43
+ uv tool install rayohx-cli
44
+ ```
45
+
46
+ or with pipx:
47
+
48
+ ```sh
49
+ pipx install rayohx-cli
50
+ ```
51
+
52
+ Check it works:
53
+
54
+ ```sh
55
+ rayohx --version
56
+ ```
57
+
58
+ ## Learn more
59
+
60
+ - [Command line guide](https://github.com/coldsofttech/RayoHX/blob/main/docs/guides/cli.md): every
61
+ option, settings, exit codes and examples
62
+ - [Changelog](CHANGELOG.md)
63
+ - Using it from Python instead? See the [`rayohx`](https://pypi.org/project/rayohx/) library
64
+ - [Report a problem](https://github.com/coldsofttech/RayoHX/issues)
65
+
66
+ ## License
67
+
68
+ Apache-2.0. See [LICENSE](LICENSE).
@@ -0,0 +1,75 @@
1
+ # CLI architecture
2
+
3
+ How `rayohx_cli` (the `rayohx` command) is put together. For using it, see the [command line guide](guides/cli.md); for working on it, see [development](development.md).
4
+
5
+ ## Layering
6
+
7
+ The command line only reads options and shows results. All the work is done by the `rayohx` library: `inspect` and `select_stream` for `info`, `Downloader` for `download`. The library never imports the command line and never prints or exits. The command line adds three runtime dependencies of its own: Typer, Click (which Typer builds on) and Rich. A unit test checks that the package imports only what it declares.
8
+
9
+ ## Modules
10
+
11
+ ```text
12
+ packages/cli/src/rayohx_cli/
13
+ __main__.py python -m rayohx_cli: calls run()
14
+ cli/
15
+ __init__.py run(), the console script: runs the app and reports unexpected errors briefly
16
+ root.py the Typer app, its help text and the options every command takes
17
+ info.py the info command
18
+ download.py the download command
19
+ lifecycle.py Ctrl-C handling, and reporting how a download ended
20
+ common.py exit codes, usage_error() and make_config()
21
+ params/ every option, defined once and shared by the commands that take it
22
+ values.py turns what was typed into engine settings (pure functions, no output)
23
+ settings.py the settings file: where it is, how it is read and checked
24
+ output.py the two Rich consoles and every way of printing
25
+ render.py the tables that info shows
26
+ format.py numbers as short text (sizes, speeds, durations)
27
+ progress/ shows a download's events: a bar, plain lines, or nothing
28
+ ```
29
+
30
+ Importing `rayohx_cli.cli` imports `info` and `download`, which register their commands on the app in `root.py`.
31
+
32
+ ## A command, step by step
33
+
34
+ 1. `run()` starts the Typer app. The root callback in `root.py` runs first: it rejects clashing global options (`--verbose` with `--quiet`, `--config` with `--no-config`), configures the output and logging, finds and loads the settings file, and hands each command its defaults.
35
+ 2. The command's options come from `params`. A value is taken from the command line first, then from a `RAYOHX_<NAME>` environment variable, then from the settings file, then from the built-in default.
36
+ 3. `make_config` builds the engine settings through `values.build_config`. A bad value raises `ConfigurationError`, which is shown as a usage error (exit code 2).
37
+ 4. `download` creates a `Downloader`, subscribes a progress reporter to its events, and runs it inside `graceful_interrupt`: the first Ctrl-C asks the download to stop cleanly, and a second one quits at once.
38
+ 5. `finish` reports how it ended. The saved path goes to stdout, a "Saved ..." line goes to stderr, and the exit code is set.
39
+
40
+ `info` skips steps 4 and 5. It inspects the playlist, marks the stream a download with the same options would pick, and prints the result as JSON (`--json`) or as tables (`render.show`).
41
+
42
+ ## Output
43
+
44
+ - **Data to stdout, everything else to stderr.** `output.data` and `output.print_json` write a command's result to the `console`. Messages, errors, progress and logs go to `err_console`, so the result can be piped or captured. Nothing uses `print`.
45
+ - **`--quiet`** hides status messages and progress; errors and the result still show. **`--no-color`** and the `NO_COLOR` variable turn colour off, and Rich also drops it when output is piped.
46
+ - **Logging.** The library's log records are shown through a console handler on stderr, so they do not tear a progress bar. `--log-file` also writes a detailed log, and a redaction filter removes secrets from what is shown.
47
+
48
+ ## Exit codes
49
+
50
+ | Code | Meaning |
51
+ | --- | --- |
52
+ | 0 | Success |
53
+ | 1 | The operation failed |
54
+ | 2 | The command or a setting was invalid |
55
+ | 130 | Stopped with Ctrl-C |
56
+
57
+ The codes are defined in `cli/common.py`. See the [exit codes guide](guides/cli/exit-codes.md) for what users see.
58
+
59
+ ## Errors
60
+
61
+ Library errors carry a message and a hint, and `output.error_from` prints both. Anything unexpected travels up to `run()`, which prints the exception type and message and exits with 1. A traceback is shown only with `--verbose`, and never with local variables, since they can hold secrets. Typer's own pretty tracebacks are switched off for the same reason.
62
+
63
+ ## Progress
64
+
65
+ A reporter is anything that can be called with a download event, plus `start()` and `close()`. There are three: a progress bar, plain lines, and one that shows nothing. `make_reporter` picks one from `--progress`. `--quiet` and `--json` always get the silent one, and `auto` chooses the bar on a terminal and plain lines otherwise.
66
+
67
+ ## Settings file
68
+
69
+ The file is TOML whose keys are option names. It is `--config`, else `rayohx.toml` in the current folder, else the per-user file (`%APPDATA%\rayohx\config.toml` on Windows, `~/.config/rayohx/config.toml` elsewhere). A key that is not an option is an error, with a "did you mean" hint, so a typo never does nothing. `url`, `output`, `json` and `help` cannot be set there. `--no-config` ignores all settings files.
70
+
71
+ ## Packaging
72
+
73
+ - The console script is `rayohx = rayohx_cli.cli:run`.
74
+ - The installers live in the root `installer/` folder: a PyInstaller one-folder build (`pyinstaller/rayohx.spec`), one Windows setup for the command line and the window (`windows/setup.nsi`) and Linux deb and rpm packages (`linux/nfpm.yaml`). Icons come from `brand/light` and the setup banners from `brand/dark`.
75
+ - The window installer carries its own copy of the command line, built the same way.
@@ -0,0 +1,79 @@
1
+ # CLI development
2
+
3
+ How to work on `packages/cli`. For how it is built, see [architecture](architecture.md); for using the command, see the [command line guide](guides/cli.md). General set-up for the whole repository is in the [project development notes](../../../docs/development.md).
4
+
5
+ ## Set up and run
6
+
7
+ ```bash
8
+ uv sync --locked # all packages and the dev tools
9
+ uv run rayohx --help # the command, from your checkout
10
+ uv run rayohx info https://example.com/master.m3u8
11
+ uv run python -m rayohx_cli download --help # the same thing, as a module
12
+ ```
13
+
14
+ ## Checks
15
+
16
+ Run only what your change touches:
17
+
18
+ ```bash
19
+ uv run pytest packages/cli/tests/unit --no-cov # unit tests
20
+ uv run pytest -m integration packages/cli/tests --no-cov # real process and local servers
21
+ uv run ruff check packages/cli
22
+ uv run ruff format --check packages/cli
23
+ uv run mypy packages/cli/src
24
+ ```
25
+
26
+ The package's own pytest settings require 80% coverage of `rayohx_cli`, so a run of a few tests fails on coverage unless you pass `--no-cov`. CI runs the same commands per package (`ci-cli.yml`), plus pre-commit on the package's files.
27
+
28
+ ## Tests
29
+
30
+ ```text
31
+ packages/cli/tests/
32
+ conftest.py fixtures shared by all tests: a clean environment, restored logging,
33
+ a CliRunner, a fake download, and the marker for integration tests
34
+ unit/ commands through typer.testing.CliRunner, and the pure modules
35
+ integration/ the installed command as a real process against a real local server,
36
+ and the built (frozen) executable
37
+ helpers/ small real HTTP servers, a fake web site and test media
38
+ frozen.py finds the executables PyInstaller built
39
+ ```
40
+
41
+ - **Unit tests** call the app with the `runner` fixture and check the exit code, stdout and stderr. Test the pure modules (`values`, `format`, `settings`) directly.
42
+ - **Everything under `integration/`** is marked `integration` automatically, so the default run leaves it out.
43
+ - **The frozen tests** need a PyInstaller build first (`uv run python installer/scripts/build.py`). Without one they are skipped. Set `RAYOHX_INSTALLER_DIR` to test a build somewhere other than `build/installer`.
44
+ - **The conftest** removes `RAYOHX_*` variables and settings files from the machine, so a test never depends on the developer's own set-up.
45
+
46
+ ## Adding an option
47
+
48
+ 1. Define it once in the right file in `params/` (selection, network, engine, output or display) and put it in that file's help panel.
49
+ 2. Add it to the signature of each command that takes it, and pass it to `make_config(...)` in that command.
50
+ 3. Handle it in `values.build_config`, and raise `ConfigurationError` for a bad value so it becomes a usage error.
51
+ 4. The environment variable `RAYOHX_<NAME>` and the settings-file key work automatically, because both use the option's name.
52
+ 5. Add unit tests for the value handling and for the command.
53
+ 6. Update the guide in `docs/guides/cli/` and the `[Unreleased]` section of `packages/cli/CHANGELOG.md`.
54
+
55
+ ## Adding a command
56
+
57
+ 1. Add a module in `cli/` with a function decorated by `@app.command()`, and import it in `cli/__init__.py` so it registers.
58
+ 2. Reuse the options in `params/`, build settings with `make_config`, and call the library for the work. Keep the command to parsing and showing.
59
+ 3. Print through `output` only: the result with `output.data` or `output.print_json`, everything else with `output.message` and `output.error_from`.
60
+ 4. End with one of the exit codes in `cli/common.py`.
61
+ 5. Document it in `docs/guides/cli/` and the changelog.
62
+
63
+ ## Rules to keep
64
+
65
+ - No `print`: the linter rejects it, and `output` keeps data on stdout and messages on stderr.
66
+ - Keep Typer's Rich help: `rich_markup_mode="rich"` on every Typer app, and escape literal square brackets in help text with a backslash.
67
+ - Never show local variables in an error, and never put headers, cookies, keys or tokens in output or logs.
68
+ - The library does the work and never imports the command line. If you need logic in the command, it probably belongs in `rayohx`.
69
+ - Explain any `# noqa` or `# nosemgrep` with a reason in the comment.
70
+
71
+ ## Building the installers
72
+
73
+ ```bash
74
+ uv sync --group installer
75
+ uv run python installer/scripts/build.py --smoke # everything this OS can build
76
+ uv run python installer/scripts/build.py --format deb,rpm --smoke # on Linux
77
+ ```
78
+
79
+ The installer files are in the root `installer/` folder; see [installer packaging](../../../installer/docs/packaging.md) and [packaging](packaging.md) for the tools you need and what each file does.
@@ -0,0 +1,34 @@
1
+ # clean
2
+
3
+ `rayohx clean` removes the working folders that interrupted downloads leave behind.
4
+
5
+ [Back to the command line guide](../cli.md)
6
+
7
+ ```bash
8
+ rayohx clean [FOLDER]... [OPTIONS]
9
+ ```
10
+
11
+ An interrupted or failed download keeps a hidden `.rayohx-<id>` folder beside its output (or, with
12
+ `--workspace`, a folder named by a short id inside that folder) so that running the same command
13
+ again can resume. If you will not resume, `clean` frees the space.
14
+
15
+ ```bash
16
+ rayohx clean # look in the current folder
17
+ rayohx clean ~/Videos --dry-run # only list what would go
18
+ rayohx clean ~/Videos --older-than 7 --yes
19
+ ```
20
+
21
+ - Give the folder you saved to (or the one you passed to `--workspace`). The default is the current
22
+ folder. Only folders directly inside it are looked at.
23
+ - Folders used by a running download are never removed.
24
+ - Removing a folder means that download starts again from the beginning. The output file itself is
25
+ never touched.
26
+ - The removed folders are printed on stdout, one per line; the sizes and a summary go to stderr.
27
+
28
+ | Option | Short | Description |
29
+ |---|---|---|
30
+ | `--older-than` | | Only folders not used for this many days. |
31
+ | `--dry-run` | | Only list what would be removed. |
32
+ | `--yes` | `-y` | Do not ask before removing. |
33
+
34
+ Without `--yes` you are asked to confirm. If you decline, the exit code is `1`.
@@ -0,0 +1,18 @@
1
+ # config
2
+
3
+ `rayohx config` shows which settings are in effect, to answer "why did it use that value?".
4
+
5
+ [Back to the command line guide](../cli.md)
6
+
7
+ ```bash
8
+ rayohx config
9
+ rayohx --config ./work.toml config --json
10
+ ```
11
+
12
+ It prints the [settings file](settings.md#the-settings-file) that would be used (or `none` and where
13
+ it looked), the values in it, and every `RAYOHX_` environment variable that is set. `--no-config`
14
+ makes it report that settings files are ignored. Values that may be secret (proxies, passwords,
15
+ cookies, headers, keys) are shown as `***`.
16
+
17
+ `--json` prints one document with `settings_file`, `searched`, `ignored`, `settings` and
18
+ `environment`.