docs/source/siteadmin/commandline-upload.rst

   1 .. MediaGoblin Documentation
   2
   3    Written in 2011, 2012 by MediaGoblin contributors
   4
   5    To the extent possible under law, the author(s) have dedicated all
   6    copyright and related and neighboring rights to this software to
   7    the public domain worldwide. This software is distributed without
   8    any warranty.
   9
  10    You should have received a copy of the CC0 Public Domain
  11    Dedication along with this software. If not, see
  12    <http://creativecommons.org/publicdomain/zero/1.0/>.
  13
  14 ======================
  15 Command-line uploading
  16 ======================
  17
  18 If you're a site administrator and have access to the server then you
  19 can use the 'addmedia' task. If you're just a user and want to upload
  20 media by the command line you can. This can be done with the pump.io
  21 API. There is `p <https://github.com/xray7224/p/>`_, which will allow you
  22 to easily upload media from the command line, follow p's docs to do that.
  23
  24 To use the addmedia command::
  25
  26   ./bin/gmg addmedia username your_media.jpg
  27
  28 This will submit the file "your_media.jpg" to be a media entry
  29 associated with the user "username".
  30
  31 You can get help on all the available options by running::
  32
  33   ./bin/gmg addmedia --help
  34
  35 Here's a longer example that makes use of more options::
  36
  37   ./bin/gmg addmedia aveyah awesome_spaceship.png \
  38       --title "My awesome spaceship" \
  39       --description "Flying my awesome spaceship, since I'm an awesome pilot" \
  40       --collection-slug i-m-an-awesome-pilot \
  41       --license "http://creativecommons.org/licenses/by-sa/3.0/" \
  42       --tags "spaceships, pilots, awesome" \
  43       --slug "awesome-spaceship"
  44
  45 You can also pass in the `--celery` option if you would prefer that
  46 your media be passed over to celery to be processed rather than be
  47 processed immediately.
  48
  49 ============================
  50 Command-line batch uploading
  51 ============================
  52
  53 There's another way to submit media, and it can be much more powerful, although
  54 it is a bit more complex.
  55
  56   ./bin/gmg batchaddmedia admin /path/to/your/metadata.csv
  57
  58 This is an example of what a script may look like. The important part here is
  59 that you have to create the 'metadata.csv' file.::
  60
  61   location,dcterms:title,dcterms:creator,dcterms:type
  62   "http://www.example.net/path/to/nap.png","Goblin taking a nap",,"Image"
  63   "http://www.example.net/path/to/snore.ogg","Goblin Snoring","Me","Audio"
  64
  65 The above is an example of a very simple metadata.csv file. The batchaddmedia
  66 script would read this and attempt to upload only two pieces of media, and would
  67 be able to automatically name them appropriately.
  68
  69 The CSV file
  70 ============
  71 The location column
  72 -------------------
  73 The location column is the one column that is absolutely necessary for
  74 uploading your media. This gives a path to each piece of media you upload. This
  75 can either a path to a local file or a direct link to remote media (with the
  76 link in HTTP format). As you can see in the example above the (fake) media was
  77 stored remotely on "www.example.net".
  78
  79 Other internal nodes
  80 --------------------
  81 There are other columns which can be used by the script to provide information.
  82 These are not stored as part of the media's metadata. You can use these columns to
  83 provide default information for your media entry, but as you'll see below, it's
  84 just as easy to provide this information through the correct metadata columns.
  85
  86 - **id** is used to identify the media entry to the user in case of an error in the batchaddmedia script.
  87 - **license** is used to set a license for your piece a media for MediaGoblin's use. This must be a URI.
  88 - **title** will set the title displayed to MediaGoblin users.
  89 - **description** will set a description of your media.
  90 - **collection-slug** will add the media to a collection, if a collection with the given slug exists.
  91
  92 Metadata columns
  93 ----------------
  94 Other columns can be used to provide detailed metadata about each media entry.
  95 Our metadata system accepts any information provided for in the
  96 `RDFa Core Initial Context`_, and the batchupload script recognizes all of the
  97 resources provided within it.
  98
  99 .. _RDFa Core Initial Context: http://www.w3.org/2011/rdfa-context/rdfa-1.1
 100
 101 The uploader may include the metadata for each piece of media, or
 102 leave them blank if they want to. A few columns from `Dublin Core`_ are
 103 notable because the batchaddmedia script also uses them to set the default
 104 information of uploaded media entries.
 105
 106 .. _Dublin Core: http://wiki.dublincore.org/index.php/User_Guide
 107
 108 - **dc:title** sets a title for your media entry.
 109 - **dc:description** sets a description of your media entry.
 110
 111 If both a metadata column and an internal node for the title are provided, MediaGoblin
 112 will use the internal node as the media entry's display name. This makes it so
 113 that if you want to display a piece of media with a different title
 114 than the one provided in its metadata, you can just provide different data for
 115 the 'dc:title' and 'title' columns. The same is true of the 'description' and
 116 'dc:description'.