should we say "whether to immediately flush" and add "if you set this to false, you will get better performance but must ensure that flush is called after all media operations are done". maybe we should add that in the class docblock instead and just add "see class docblock" here.