Crate rsynko_media

Expand description

§rsynko-media

rsynko-media states what a media item is, how it is described, chosen, produced, and named, and how those meanings compose into one download program. These specifications are always used together, so they live together as modules of one package. It chooses no extractor, network library, serialization format, or filesystem.

§Observation

An observation record is an open, keyed, heterogeneous collection of values. It is open because an extractor may state fields the core has never heard of, keyed because later fields with equal keys replace earlier ones, and heterogeneous because sources describe themselves in whatever shapes they use. MetadataAlg constructs records and values in an interpreter-chosen carrier; InfoRecord and InfoValue reify them.

A format denotes one alternative representation of a media item: an identity together with everything observed about it. It fixes no schema. Where its bytes rest, which streams it carries, its container, and every quantity selection compares are observations. An artifact denotes one produced file the same way, classified by the role it plays.

FormatAlg defines one format from an identity and everything observed about it, and FormatViewAlg observes one named value back. A derived operation composes the three without naming a representation:

use alux_ext::ext;
use rsynko_media::{FORMAT_EXTENSION, FORMAT_SOURCE, FormatAlg, FormatViewAlg, MetadataAlg};

#[ext(name = LocatedFormatExt)]
impl<This> This
where
    This: MetadataAlg + FormatAlg + FormatViewAlg,
{
    /// Defines one format from where its bytes rest and the container it states.
    fn located_format(&self, id: &str, url: &str, extension: &str) -> This::Format {
        self.format(
            id,
            self.metadata([
                (FORMAT_SOURCE.to_owned(), self.string_metadata(url)),
                (FORMAT_EXTENSION.to_owned(), self.string_metadata(extension)),
            ]),
        )
    }

    /// Observes where a format's bytes rest, exactly when it stated that.
    fn located_source<'a>(&self, format: &'a This::Format) -> Option<&'a str> {
        self.format_text(format, FORMAT_SOURCE)
    }
}

The well-known keys named here — FORMAT_SOURCE, FORMAT_EXTENSION, FORMAT_HAS_AUDIO, FORMAT_HAS_VIDEO, ARTIFACT_LOCATION — are conventions, not fields. An extractor that states them gains the derived observations; one that does not is still complete, and an operation needing an unstated observation says so rather than inventing a value.

§Extraction

An extraction result denotes one playable media description, a reference requiring another extraction, or an ordered collection of further results. ExtractionCatalogAlg exposes extractor order and acceptance, ExtractionApplyAlg applies one selected key, and ExtractionExt derives first-accepting choice and URL extraction from exactly those two.

ExtractionAlg defines those three shapes, ExtractionViewAlg observes when a result denotes exactly one media item, and MediaViewAlg observes that item’s identity, title, and formats in extractor order.

§Selection

A catalog’s order means increasing preference. Every predicate primitive except identity ranges over observations, so one set of primitives speaks about any field an extractor recorded. FormatPredicateExt derives the named predicates — has_audio, has_video, format_extension — and the comparisons at_most, at_least, exactly, less_than, and greater_than from them. FormatPredicateMatchAlg observes whether one format satisfies one predicate, and FormatSelectionApplyAlg interprets a whole program against a catalog. Interpreting reified syntax is an interpreter rather than a derived operation, so interpret_selection states the canonical fold and an interpreter that chose the reified sorts delegates to it.

FormatPredicateAlg constructs the primitives, FormatSelectionAlg composes them into best, worst, merge, and fallback programs, and FormatSelectionApplyAlg interprets a whole program against a catalog.

Interpreting that program against a catalog is FormatSelectionApplyAlg, and a reference interpreter for these sorts lives in rsynko-memory.

§Processing and output

A processing program denotes an ordered sequence of named artifact transformations, each assigned to one stage. Interpreting a program applies every step in declaration order; interpreting a stage applies the subsequence belonging to it without reordering. Portable output naming is a separate pure meaning: it admits one Linux and Windows safe file component, bounds the stem, and falls back to a stated identity.

§The composed program

FormatSourceAlg is the only bridge from a selected format to a retrieval carrier, and it may state that a format cannot be located from what was observed. MediaDownloadExt::download_extraction and ApplicationExt::download_url compose extraction, selection, naming, and one-resource download over that bridge. A protocol specification specializes the source description while preserving every other meaning.

use alux_ext::ext;
use rsynko_download::{
    AtomicPublishAlg, DownloadObservationAlg, DownloadProgressAlg, DownloadReportAlg,
    FetchStreamAlg,
};
use rsynko_media::{
    ExtractionViewAlg, FormatPredicateAlg, FormatSelectionAlg, FormatSelectionApplyAlg,
    FormatSelectionProgramExt, FormatSourceAlg, FormatViewAlg, MediaDownloadError,
    MediaDownloadExt, MediaViewAlg, OutputTarget,
};
use std::fmt::Display;
use std::path::PathBuf;

#[ext(name = PreferredMediaExt)]
impl<This, Source, FetchError, Stream, PublishError, Event, Progress> This
where
    This: ExtractionViewAlg
        + MediaViewAlg
        + FormatViewAlg
        + FormatPredicateAlg
        + FormatSelectionAlg
        + FormatSelectionApplyAlg
        + FormatSourceAlg<Source>
        + FetchStreamAlg<Source, Error = FetchError, Stream = Stream>
        + AtomicPublishAlg<Error = PublishError>
        + DownloadObservationAlg<Event = Event, Progress = Progress>
        + DownloadProgressAlg<Progress = Progress>
        + DownloadReportAlg<Event = Event>,
    FetchError: Display,
    PublishError: Display,
{
    /// Publishes one extraction through the named format, falling back to the best progressive one.
    fn download_preferred(
        &self,
        extraction: This::Extraction,
        format_id: &str,
        target: &OutputTarget,
    ) -> Result<PathBuf, MediaDownloadError<FetchError, PublishError>> {
        let selection = self.preferred_progressive_format(format_id);
        self.download_extraction(extraction, &selection, target)
    }
}

§Laws

the empty observation record is neutral, later equal keys replace earlier ones, and observation is total into an option;
an unstated truth denotes falsity, and a typed observation succeeds exactly when the stated value has that type;
choosing returns the first accepting extractor, and no extractor exactly when no catalog entry accepts the URL;
extracting a supported URL applies exactly the chosen extractor and an unsupported URL applies none;
Best and Worst differ only by which end of the same preference order they choose;
Merge succeeds exactly when every child succeeds and preserves child order, and Fallback is left-biased;
a predicate speaking about an unstated observation accepts no format;
the empty processing program is an identity, concatenation denotes sequential composition, stage selection preserves declaration order, and failure stops interpretation before later steps;
portable naming depends only on the stated title, fallback identity, and extension;
extraction happens before selection, exactly one selected format is required, naming depends only on the extraction, selected format, and output target, and the source FormatSourceAlg produces is passed unchanged to the generic download meaning.

Macros§

ambassador_impl_ArtifactAlg: A macro to be used by ambassador::Delegate to delegate ArtifactAlg
ambassador_impl_ExtractionAlg: A macro to be used by ambassador::Delegate to delegate ExtractionAlg
ambassador_impl_ExtractionApplyAlg: A macro to be used by ambassador::Delegate to delegate ExtractionApplyAlg
ambassador_impl_ExtractionCatalogAlg: A macro to be used by ambassador::Delegate to delegate ExtractionCatalogAlg
ambassador_impl_ExtractionViewAlg: A macro to be used by ambassador::Delegate to delegate ExtractionViewAlg
ambassador_impl_FormatAlg: A macro to be used by ambassador::Delegate to delegate FormatAlg
ambassador_impl_FormatPredicateAlg: A macro to be used by ambassador::Delegate to delegate FormatPredicateAlg
ambassador_impl_FormatPredicateMatchAlg: A macro to be used by ambassador::Delegate to delegate FormatPredicateMatchAlg
ambassador_impl_FormatSelectionAlg: A macro to be used by ambassador::Delegate to delegate FormatSelectionAlg
ambassador_impl_FormatSelectionApplyAlg: A macro to be used by ambassador::Delegate to delegate FormatSelectionApplyAlg
ambassador_impl_FormatViewAlg: A macro to be used by ambassador::Delegate to delegate FormatViewAlg
ambassador_impl_MediaViewAlg: A macro to be used by ambassador::Delegate to delegate MediaViewAlg
ambassador_impl_MetadataAlg: A macro to be used by ambassador::Delegate to delegate MetadataAlg A macro to be used by ambassador::Delegate to delegate MetadataAlg A macro to be used by ambassador::Delegate to delegate MetadataAlg
ambassador_impl_MetadataViewAlg: A macro to be used by ambassador::Delegate to delegate MetadataViewAlg A macro to be used by ambassador::Delegate to delegate MetadataViewAlg A macro to be used by ambassador::Delegate to delegate MetadataViewAlg
ambassador_impl_OutputNameAlg: A macro to be used by ambassador::Delegate to delegate OutputNameAlg
ambassador_impl_ProcessingProgramAlg: A macro to be used by ambassador::Delegate to delegate ProcessingProgramAlg

Enums§

ApplicationError: Denotes failure of an ordinary direct-resource media program.
ArtifactKind: Classifies a produced artifact by its semantic role.
CollectionKind: Classifies an ordered extraction collection.
ExtractUrlError: Denotes failure to derive extraction from an input URL.
FormatComparison: Denotes how an observed number is compared against a stated one.
MediaDownloadError: Denotes failure after extraction has produced a media description.
OutputTarget: Selects how a final output path is denoted.
ProcessingStage: Names the public processing stages in their product order.

Constants§

ARTIFACT_LOCATION: Names the observation stating where an artifact currently rests.
FORMAT_EXTENSION: Names the observation stating a format’s container or filename extension.
FORMAT_HAS_AUDIO: Names the observation stating whether a format contains audio.
FORMAT_HAS_VIDEO: Names the observation stating whether a format contains video.
FORMAT_SOURCE: Names the observation locating a format’s bytes when an extractor states one.

Traits§

ApplicationExt: Derives ordinary extraction, format selection, destination naming, and download.
ArtifactAlg: Provides the carrier and constructor for produced artifacts.
ArtifactLaws: Authors the produced-artifact laws.
ExtractionAlg: Provides the carriers and constructors for extraction results.
ExtractionApplyAlg: Specifies application of one selected extractor.
ExtractionCatalogAlg: Specifies an ordered catalog of extractor meanings.
ExtractionExt: Derives ordered extractor choice and URL extraction from primitive capabilities.
ExtractionLawFixture: Supplies the catalog-dependent inputs an extraction scenario cannot author for itself.
ExtractionLaws: Authors the ordered-extractor-choice laws over a catalog the interpreter supplies.
ExtractionViewAlg: Specifies observation of what shape an extraction result denotes.
FormatAlg: Provides the carriers and constructor for one alternative representation.
FormatLaws: Authors the format-observation laws.
FormatPredicateAlg: Provides the carrier and primitive constructors for format predicates.
FormatPredicateExt: Derives named and comparative predicates from primitive observation construction.
FormatPredicateMatchAlg: Specifies interpretation of reified format predicates.
FormatSelectionAlg: Provides the carrier and primitive constructors for selection programs.
FormatSelectionApplyAlg: Specifies interpretation of a selection program against a preference-ordered catalog.
FormatSelectionProgramExt: Derives common selection programs by equating predicate carriers.
FormatSourceAlg: Specifies how one generic format denotes a retrievable source carrier.
FormatViewAlg: Specifies observation of what one format states about itself.
MediaDownloadExt: Derives selection, naming, and download for an already extracted result.
MediaOutputExt: Derives a final path from media observations, the selected format, and the output target.
MediaProgramLawFixture: Supplies the retrieval inputs a media-program scenario cannot author for itself.
MediaProgramLaws: Authors the composed media-download laws.
MediaSorts: The sorts of media meaning — the Rust encoding of the type families the media algebra classes share.
MediaViewAlg: Specifies the observations one media item offers.
MetadataAlg: Provides the carriers and constructors for open metadata.
MetadataExt: Derives concise metadata records from primitive construction.
MetadataViewAlg: Specifies reading back what one metadata record states.
ObservationLaws: Authors the open-record laws.
OutputNameAlg: Provides the carrier and constructor for one portable output name.
OutputNameExt: Derives portable output names independently of their carrier.
OutputNameLaws: Authors the portable-output-naming laws.
ProcessingApplicationLaws: Authors the processing-application laws.
ProcessingApplyAlg: Specifies application of primitive artifact-processing steps.
ProcessingExt: Derives complete-program and single-stage processing from primitive step application.
ProcessingLawFixture: Supplies the application trace a processing scenario cannot author for itself.
ProcessingLaws: Authors the processing-program laws.
ProcessingProgramAlg: Provides the carriers and primitive constructors for processing programs.
ProcessingProgramExt: Derives concise processing-program construction.
ProcessingProgramViewAlg: Specifies observation of a reified processing program.
ProcessingSorts: The sorts of artifact-processing meaning.
SelectionLaws: Authors the selection-program laws.

Functions§

portable_file_name: Derives a portable file name from a title, fallback identity, and selected extension.
portable_file_stem: Derives a portable single-component file stem from a title and fallback identity.
portable_user_file_name: Normalizes an edited file name while preserving a valid explicit extension.