hydra-file_characterization

Code: Gem Version Build Status Coverage Status

Docs: Contribution Guidelines Apache 2.0 License

Community Support: Samvera Community Slack

What is hydra-file_characterization?

Provides a wrapper for file characterization.

Supported versions

This software is currently tested against:

  • FITS 1.4.1
  • Ruby 2.6, 2.7, and 3.0
  • Rails 6.0, 6.1, and 7.0

Product Owner & Maintenance

hydra-file_characterization was a Core Component of the Samvera Community. Given a decline in available labor required for maintenance, this project no longer has a dedicated Product Owner. The documentation for what this means can be found here.

Product Owner

Vacant

Until a Product Owner has been identified, we ask that you please direct all requests for support, bug reports, and general questions to the #dev Channel on the Samvera Slack.

Help

The Samvera community is here to help. Please see our support guide.

Getting Started

If you are using Rails add the following to an initializer (./config/initializers/hydra-file_characterization_config.rb):

Hydra::FileCharacterization.configure do |config|
  config.tool_path(:fits, '/path/to/fits')
end
Hydra::FileCharacterization.characterize(File.read(filename), File.basename(filename), :fits)
  • Why file.read? To highlight that we want a string. In the case of ActiveFedora, we have a StringIO instead of a file.
  • Why file.basename? In the case of Fits, the characterization takes cues from the extension name.

You can call a single characterizer...

xml_string = Hydra::FileCharacterization.characterize(File.read("/path/to/my/file.rb"), 'file.rb', :fits)

...for this particular call, you can specify custom fits path...

xml_string = Hydra::FileCharacterization.characterize(contents_of_a_file, 'file.rb', :fits) do |config|
  config[:fits] = './really/custom/path/to/fits'
end

...or even make the path callable...

xml_string = Hydra::FileCharacterization.characterize(contents_of_a_file, 'file.rb', :fits) do |config|
  config[:fits] = lambda {|filename|  }
end

...or even create your custom characterizer on the file...

xml_string = Hydra::FileCharacterization.characterize(contents_of_a_file, 'file.rb', :my_characterizer) do |config|
  config[:my_characterizer] = lambda {|filename|  }
end

You can also call multiple characterizers at the same time.

fits_xml, ffprobe_xml = Hydra::FileCharacterization.characterize(contents_of_a_file, 'file.rb', :fits, :ffprobe)

Registering New Characterizers

This is possible by adding a characterizer to the Hydra::FileCharacterization::Characterizers namespace.

Contributing

Running the tests:

  • Install FITS v1.4.1, which is the most recent version we've tested against.

    mkdir ~/fits
    wget "https://github.com/harvard-lts/fits/releases/download/1.4.1/fits-1.4.1.zip"
    unzip -d ~/fits/ "fits-1.4.1.zip"
    chmod a+x ~/fits/fits.sh
    ln -s ~/fits/fits.sh ~/fits/fits
    rm "fits-1.4.1.zip"
    
  • Once FITS is installed, you should be able to run the tests with: rspec spec

If you're working on PR for this project, create a feature branch off of main.

This repository follows the Samvera Community Code of Conduct and language recommendations. Please do not create a branch called master for this repository or as part of your pull request; the branch will either need to be removed or renamed before it can be considered for inclusion in the code base and history of this repository.

Releasing

  1. bundle install
  2. Increase the version number in lib/hydra/file_characterization/version.rb
  3. Increase the same version number in .github_changelog_generator
  4. Update CHANGELOG.md by running this command:
  github_changelog_generator --user samvera --project hydra-file_characterization --token YOUR_GITHUB_TOKEN_HERE
  1. Commit these changes to the master branch
  2. Run rake release

Acknowledgments

This software has been developed by and is brought to you by the Samvera community. Learn more at the Samvera website.

Samvera Logo