Command length and general user convenience

[XorUnison]

I think we'll have to drag this issue in the open and properly discuss it, rather sooner than later.

Right now the code supports a wide range of arguments for some desired parameters. For instance using medium quality.
-m
-r medium
-r 720,1280 (although this would default to 60FPS, not 30)
--medium_quality
--resolution medium

Personally I'm fine with that. It's not like this is adding over hundred lines of code, when reading the code it's easy to isolate and skip these areas, and the performance overhead is almost certainly not even anywhere near being measurable.

Now we have people like @huguesdevimeux who are for cutting down some of that (#64), with which I could live. Although I think that's not really necessary.

We also have @eulertour with statements like... this here on my current PR:

At some point these should probably be merged into a single --render_quality flag which takes 4 arguments.

Let's also make properly clear what's at stake with decisions like these.
Currently, and particularly with my pending constants.py changes we can drive manim like this:
manim project scene -psm
I like it that way. When working on my projects I usually have to re-render stuff a lot, and for very different reasons, so using it like this I often switch the m for an l, or remove it, or, now with the new changes, add a k. I can quickly get manim to get me what I need.

On the other hand it sounds like @eulertour is more in favor of enforcing people to have to use manim like this:
manim C:\FullProjectFolderName\project.py scene --media_dir D:\SomeOtherProbablyNotSuperShortAbsolutePath --preview --save_last_frame --render_quality medium

Now I don't know about you, but for me, that there is just ugly and panic inducing in the extreme. I unironically estimate that if I always had to use manim like this then my recent video would've probably included a couple real extra hours of work, solely dedicated to writing out and copypasting commands. Please, for the love of deer goats, let's not go there. Yes?

If anything, manim is tool. It's code is there for us to create something that is as powerful and convenient to use as possible. We should never sacrifice even the tiniest bit of either of those unless there's substantial gains for the other we can't get otherwise. I'd even argue we should add the ability to define FPS in the arguments as opposed to having it only tethered to predefined qualities. And maybe add an addition to not just start at a specific animation but also end at one as opposed to always rendering through to the end.

Thoughts and opinions?

[kilacoda-old]

I concur. We don't want to make manim as complicated as something like ffmpeg

[kilacoda-old]

Besides, how does having shortcuts hurt @eulertour?

[leotrs]

-m
-r medium
-r 720,1280 (although this would default to 60FPS, not 30)
--medium_quality
--resolution medium

IMO, this is confusing. A new user will not necessarily know that these are all available, and may (understandably) think that these are doing different things. I think this should change.

On the larger issue of accepting long/many arguments. I think there is a notion here of options that should always apply for a project, vs options that I will change from execution to execution even within the same project. For example, for a single project, I am unlikely to change the media_dir more than a few times. But I am likely to render in different resolutions while working on the same project. Concretely, I think the resolution flag will be used much more frequently than the media_dir flag. I suggest that we separate all of the less-frequently used options and put them in a .cfg file. The more frequently options should stay, and they should be easy to change, which means having single-letter flags.

[huguesdevimeux]

I agree with @leotrs .
Aside, I think the flags aren't organized well. In my opinion, we should have 4 sorts of flags :
The first one would be something with related to quality in general as it is currently (--low_quality, etc ..) that would contain a preset of settings (pixel_height, pixel_width , frame_rate). I think this is enough for most of the users.
But, the 3 others flags would be used to customize these settings: -d for the definition, -f for the framerate.

PS : We should pay attention to the fact that resolution != definition. Resolution is in Pixels per one inch and definition is the size of the video (1920 x 1080). I wanted to do a PR about that but it would have been useless since we are going to rebuild the whole thing.

[leotrs]

We don't want to make manim as complicated as something like ffmpeg

But manim does use ffmpeg. Is there a way to grab extra CLI arguments and send them to ffmpeg? This would save us a lot of implementation and just rely on what ffmpeg already provides.

[XorUnison]

IMO, this is confusing. A new user will not necessarily know that these are all available, and may (understandably) think that these are doing different things. I think this should change.

Well, -h is dropping information about what these do, although honestly it's really lacking. I've added brief mentions of render time to the different qualities in my PR, because it's everything but obvious that high quality is actually below production quality. In the first place, if you don't look into the code you never either hear of this so called production quality, nor are you going to find out what resolution and FPS it is until the very moment you inspect a finished file. This is kinda bad. When I go -h on a cmd tool I expect to find out what's up in a concise, but adequately verbose manner. Neither as a user, nor as a dev do I always want to be forced to go into the code to understand what everyday arguments do. So I agree, it is confusing. If we actually want to take options away we'll want to carefully decide which ones. The shortest commands should absolutely stay, because as I said, convenience of use. And we'll want to rework -h to explain stuff better, not worse.

On the larger issue of accepting long/many arguments. I think there is a notion here of options that should always apply for a project, vs options that I will change from execution to execution even within the same project. For example, for a single project, I am unlikely to change the media_dir more than a few times. But I am likely to render in different resolutions while working on the same project. Concretely, I think the resolution flag will be used much more frequently than the media_dir flag. I suggest that we separate all of the less-frequently used options and put them in a .cfg file. The more frequently options should stay, and they should be easy to change, which means having single-letter flags.

I have never seriously used --media_dir until the moment I had to work with it to test my PR. I have one HDD, and on it one folder where I want my stuff to go, and that's it. In vanilla manim I did that by using the DIR variables in constants.py, which my PR moves to it's own file, because of course every time constants.py was updated that spelt trouble.
I'm also all for a .cfg file. The dirs.py in my PR is basically a prototype for that exact paradigm. Something the user can set once and forget, and that (after we're done with it) won't have to be changed again, or only very, very rarely.

I agree with @leotrs .
Aside, I think the flags aren't organized well. In my opinion, we should have 4 sorts of flags :
The first one would be something with related to quality in general as it is currently (--low_quality, etc ..) that would contain a preset of settings (pixel_height, pixel_width , frame_rate). I think this is enough for most of the users.
But, the 3 others flags would be used to customize these settings: -d for the definition, -f for the framerate.

Preset flags and manual specification flags. Sure that'd be fine.
Small nitpick, when we introduce a framerate flag it's gonna have to be something else since -f is used. Like I had to use -e for high quality because any and all other proper letters were taken.

PS : We should pay attention to the fact that resolution != definition. Resolution is in Pixels per one inch and definition is the size of the video (1920 x 1080). I wanted to do a PR about that but it would have been useless since we are going to rebuild the whole thing.

I think you're SoL with that point. Even when you go into the Windows system settings and look for definition to change your "definition" you won't even find the setting. It's called resolution. Even Wikipedia defines resolution first as the number of pixels, not density, before it's throwing the caveats into the discussion. If we pick up the torch of definition versus resolution we're just going to confuse the living daylights out of users. Best to just drop it and move on.

[leotrs]

Let me try to gather the current action items.

1. Identify which things should be constants (never change), go on config files (things that almost never change, like project-wide settings), and which things may change frequently (like resolution).
2. The first kind of things should go to a constants file, which already exists. The second kind should go on a .cfg file which does not yet exist. The third kind should be kept as cli arugments.
3. The cli arguments should have a short-hand (one letter) version, and a succinct but clear description, to be displayed when showing the help (with the -h flag).
4. Decide which cli argument will have a default value, and what that value should be.
5. Decide how much flexibility we want our cli arguments to have. For example, do we want to expose every single argument supported by ffmpeg?
6. Regarding "production quality": we need to either expose it to the user, or delete it from the code base. This is the default (so it is exposed to the user), but it is not documented anywhere. It is also not clear whether this equals any of the others (low, medium, high). We should document it better, include in the description output by -h.

Please feel free to continue discussing these, they are not set in stone. I just don't want things to fall out of the radar.

[XorUnison]

6. Regarding "production quality": we need to either expose it to the user, or delete it from the code base.

Just a quick and immediate interjection here, "production quality" is the preset manim uses when you pass no resolution arguments at all, so deleting it from the code base would be... bad. As such it's also "exposed" since it's the default. We should just have -h stating the resolution somewhere.

[leotrs]

@XorUnison thanks, ammended.